diff --git a/PENDING-ISSUES.md b/PENDING-ISSUES.md index 30c518ac..99b682ad 100644 --- a/PENDING-ISSUES.md +++ b/PENDING-ISSUES.md @@ -1,17 +1,11 @@ # Pending Issues -**Last Updated:** December 14, 2025 - ---- - ## 🔴 Django Admin - Logo Missing on Subpages **Issue:** "IGNY8 Admin" logo with rocket icon appears on homepage but not on model list/detail/edit pages. **Expected:** Logo should appear consistently across all admin pages (homepage, app index, and all model subpages). -**Status:** Fix implemented by calling `admin_site.each_context()` in `Igny8ModelAdmin._inject_sidebar_context()` to get full Unfold branding context. Needs testing verification. - --- ## 🔴 AI FUunctions progress modals texts and counts to be fixed @@ -19,4 +13,6 @@ ## 🔴 Improve the metrics below tbale son all module pages, with actiionable metrics and steps -## 🔴 Align prompts with teh strategy \ No newline at end of file +## 🔴 Align prompts with teh strategy + +## 🔴 user randomly logs out often, diff --git a/docs/PRE-LAUNCH/ADMIN-IMPLEMENTATION-STATUS.md b/docs/PRE-LAUNCH/ADMIN-IMPLEMENTATION-STATUS.md deleted file mode 100644 index 020efd66..00000000 --- a/docs/PRE-LAUNCH/ADMIN-IMPLEMENTATION-STATUS.md +++ /dev/null @@ -1,281 +0,0 @@ -# Django Admin Implementation Status - -**Last Updated:** December 15, 2025 - ---- - -## Phase Completion Status - -### ✅ Phase 0: Foundation - COMPLETED (Dec 14, 2025) - -**What was completed:** -- [x] Installed django-unfold==0.73.1 -- [x] Configured UNFOLD settings in settings.py -- [x] Updated all admin classes to inherit from Unfold ModelAdmin -- [x] Fixed admin site inheritance (Igny8AdminSite extends UnfoldAdminSite) -- [x] Fixed UserAdmin popup styling (multiple inheritance: BaseUserAdmin + ModelAdmin) -- [x] Updated Celery admin to use Unfold filters -- [x] Configured middleware (simple_history) -- [x] Rebuilt Docker images -- [x] All containers running healthy - -**Result:** Single clean Unfold admin system with no conflicts. All styling handled by Unfold automatically. - ---- - -### ✅ Phase 1: Configuration Cleanup - COMPLETED (Dec 14, 2025) - -**Completed:** -- [x] UserAdmin popup styling fix -- [x] Verified no unused site_building models in site.py (already clean) -- [x] Verified duplicate registrations already commented out in business/billing/admin.py -- [x] Added PlanLimitUsage admin registration -- [x] PlanLimitUsage already in sidebar (Billing & Tenancy group) -- [x] All model links verified working - -**Files modified:** -- `/data/app/igny8/backend/igny8_core/modules/billing/admin.py` - Added PlanLimitUsageAdmin - -**Result:** Admin configuration is clean and organized. All models properly registered and grouped. - ---- - -### ✅ Phase 2: Bulk Operations & Export - COMPLETED (Dec 14, 2025) - -**Completed:** -- [x] Added ExportMixin to Keywords admin (already had export) -- [x] Created KeywordsResource class for export configuration -- [x] Added Unfold advanced filters to Tasks admin (ChoicesDropdownFilter, RelatedDropdownFilter, RangeDateFilter) -- [x] Added Unfold advanced filters to Content admin (RangeNumericFilter for word_count, enhanced search) -- [x] Added Unfold advanced filters to Keywords admin (RangeNumericFilter for volume/difficulty, full filter set) -- [x] Added Unfold advanced filters to Clusters admin (RangeNumericFilter, RangeDateFilter) -- [x] Added Unfold advanced filters to ContentIdeas admin (comprehensive filter set) -- [x] Verified existing bulk actions (Tasks: status changes, Content: status changes, Keywords: cluster assignment) -- [x] **NEW:** Added export to Account admin with AccountResource -- [x] **NEW:** Added export to Site admin with SiteResource -- [x] **NEW:** Added export to User admin with UserResource -- [x] **NEW:** Added bulk enable/disable actions to AutomationConfig admin -- [x] **NEW:** Added export to PublishingRecord admin with PublishingRecordResource -- [x] **NEW:** Added bulk retry_failed action to PublishingRecord admin -- [x] **NEW:** Added export to SyncEvent admin with SyncEventResource -- [x] **NEW:** Added bulk sync actions to SiteIntegration admin (enable/disable/trigger sync) -- [x] **CRITICAL FIX:** Fixed Issue #5 - Custom sidebar now appears on ALL admin pages (not just home/group pages) -- [x] Backend restarted successfully - -**Files modified:** -- `/data/app/igny8/backend/igny8_core/modules/writer/admin.py` - Added Unfold filters to TasksAdmin and ContentAdmin -- `/data/app/igny8/backend/igny8_core/modules/planner/admin.py` - Added Unfold filters to KeywordsAdmin, ClustersAdmin, ContentIdeasAdmin -- `/data/app/igny8/backend/igny8_core/auth/admin.py` - Added export to Account, Site, User admins -- `/data/app/igny8/backend/igny8_core/business/automation/admin.py` - Added bulk enable/disable actions -- `/data/app/igny8/backend/igny8_core/business/publishing/admin.py` - Added export and bulk retry action -- `/data/app/igny8/backend/igny8_core/business/integration/admin.py` - Added export and bulk sync actions -- `/data/app/igny8/backend/igny8_core/admin/site.py` - **CRITICAL:** Fixed sidebar to appear on all pages - -**Critical Bug Fixed:** -- **Issue #5:** Custom sidebar with organized groups now displays consistently on: - - ✅ `/admin/` (home page) - - ✅ `/admin/{group-level-page}/` (app index pages) - - ✅ `/admin/{app}/{model}/` (model list pages) - **NOW FIXED** - - ✅ `/admin/{app}/{model}/{id}/change/` (model detail pages) - **NOW FIXED** - -**Result:** -- Admin interfaces now have modern date range pickers, numeric sliders, and searchable dropdowns -- Export functionality added to 10+ critical models (Account, Site, User, Payment, Keywords, Publishing, Sync Events) -- Bulk operations added to Automation, Publishing, and Integration modules -- **Custom sidebar navigation is now consistent across ALL admin pages** -- Better UX for filtering large datasets and managing operations at scale - ---- - -### ✅ Phase 3: Monitoring & Dashboards - COMPLETED (Dec 14-15, 2025) - -**Completed:** -- [x] Installed django-celery-results for task monitoring -- [x] Created CeleryTaskResultAdmin with colored status and execution time -- [x] Created CeleryGroupResultAdmin with result count display -- [x] Fixed celery import issue (added `from celery import current_app`) -- [x] Fixed execution_time format_html ValueError bug -- [x] Added retry_failed_tasks action to Celery admin -- [x] Added clear_old_tasks action to Celery admin -- [x] Created admin_dashboard view with 6 metric cards -- [x] Created dashboard.html template with Tailwind styling -- [x] Added AdminAlerts utility class for system alerts -- [x] Integrated alerts into dashboard -- [x] Added dashboard route to admin site URLs -- [x] Added index redirect to dashboard (auto-redirect from /admin/) -- [x] All Celery admin pages verified working (200 status) - -**Files created:** -- `/data/app/igny8/backend/igny8_core/admin/dashboard.py` - Dashboard view with metrics -- `/data/app/igny8/backend/igny8_core/admin/alerts.py` - Alert system utility -- `/data/app/igny8/backend/igny8_core/admin/celery_admin.py` - Celery task monitoring -- `/data/app/igny8/backend/igny8_core/templates/admin/dashboard.html` - Dashboard template - -**Files modified:** -- `/data/app/igny8/backend/igny8_core/admin/site.py` - Added dashboard route and index redirect -- `/data/app/igny8/backend/igny8_core/admin/apps.py` - Registered Celery admins - -**Critical Bugs Fixed:** -- **ValueError in execution_time:** Fixed format_html usage with format specifiers -- **GroupResult 500 error:** Created and registered CeleryGroupResultAdmin - -**Result:** Full operational monitoring dashboard with Celery task tracking, system alerts, and health metrics. - ---- - -### 🔄 Phase 4: Analytics & Reporting - IN PROGRESS (Dec 15, 2025) - -**Completed:** -- [x] Created reports.py module with 4 report views -- [x] Implemented revenue_report (6-month revenue, plan distribution, payment methods) -- [x] Implemented usage_report (credit usage by operation, top consumers, model usage) -- [x] Implemented content_report (30-day production timeline, content by type, word counts) -- [x] Implemented data_quality_report (orphaned content, missing relationships, negative credits) -- [x] Created all 4 report templates (revenue.html, usage.html, content.html, data_quality.html) -- [x] Integrated Chart.js 4.4.0 for data visualizations -- [x] Added 4 report routes to admin site URLs -- [x] Added Reports & Analytics section to sidebar with 4 report links -- [x] Permission checks added (@staff_member_required decorator on all reports) -- [x] Admin context merged in all reports for sidebar consistency -- [x] Backend restarted successfully - -**Remaining Tasks:** -- [ ] Test all 4 reports with real production data -- [ ] Optimize report queries for performance (add select_related, prefetch_related) -- [ ] Add caching to dashboard metrics (optional) - -**Note:** Reports are fully functional and accessible via sidebar. Testing with production data and query optimization can be done as needed during operations. - -**Files created:** -- `/data/app/igny8/backend/igny8_core/admin/reports.py` - 4 report views with analytics -- `/data/app/igny8/backend/igny8_core/templates/admin/reports/revenue.html` - Revenue analytics with Chart.js -- `/data/app/igny8/backend/igny8_core/templates/admin/reports/usage.html` - Credit usage analytics -- `/data/app/igny8/backend/igny8_core/templates/admin/reports/content.html` - Content production metrics -- `/data/app/igny8/backend/igny8_core/templates/admin/reports/data_quality.html` - Data integrity checks - -**Files modified:** -- `/data/app/igny8/backend/igny8_core/admin/site.py` - Added 4 report routes and sidebar links - -**Result:** Full analytics and reporting suite with Chart.js visualizations, accessible via admin sidebar. Reports show revenue trends, credit usage patterns, content production metrics, and data quality issues. - ---- - -### ✅ Phase 5: Advanced Features - COMPLETED (Dec 15, 2025) - -**Completed:** -- [x] Enabled list_editable for Tasks admin (status field) -- [x] Enabled list_editable for Keywords admin (status field) -- [x] Added HistoricalRecords to Payment model -- [x] Added HistoricalRecords to Account model -- [x] Added HistoricalRecords to CreditCostConfig model -- [x] Created and ran migrations for history tables -- [x] Updated Payment, Account, CreditCostConfig admins to use SimpleHistoryAdmin -- [x] Created permission groups (Content Manager, Billing Admin, Support Agent) -- [x] Assigned appropriate permissions to each group - -**Files created:** -- `/data/app/igny8/backend/igny8_core/auth/migrations/0017_add_history_tracking.py` - Account history migration -- `/data/app/igny8/backend/igny8_core/modules/billing/migrations/0017_add_history_tracking.py` - Payment & CreditCostConfig history migrations -- `/data/app/igny8/backend/igny8_core/management/commands/create_admin_groups.py` - Permission groups command -- `/data/app/igny8/backend/create_groups.py` - Standalone script for group creation - -**Files modified:** -- `/data/app/igny8/backend/igny8_core/modules/writer/admin.py` - Added list_editable=['status'] -- `/data/app/igny8/backend/igny8_core/modules/planner/admin.py` - Added list_editable=['status'] -- `/data/app/igny8/backend/igny8_core/business/billing/models.py` - Added history to Payment, CreditCostConfig -- `/data/app/igny8/backend/igny8_core/auth/models.py` - Added history to Account -- `/data/app/igny8/backend/igny8_core/modules/billing/admin.py` - Updated to use SimpleHistoryAdmin -- `/data/app/igny8/backend/igny8_core/auth/admin.py` - Updated to use SimpleHistoryAdmin - -**Permission Groups Created:** -1. **Content Manager** (18 permissions) - - Can add, change, view: Content, Tasks, Images, Keywords, Clusters, Content Ideas - - No delete permissions (safety) - -2. **Billing Admin** (20 permissions) - - Full access: Payment, Invoice, Credit Transaction, Credit Usage Log - - Can view accounts for billing context - -3. **Support Agent** (4 permissions) - - Read-only access: Content, Tasks, Accounts, Sites - - Perfect for customer support role - -**Result:** Full audit trail for financial and account changes, quick inline editing for tasks/keywords, and role-based access control via permission groups. - ---- - -## Key Achievements - -1. **✅ NO Custom CSS/Styling Needed** - - Unfold handles all UI/UX automatically - - Modern Tailwind-based design out of the box - - Dark mode support built-in - - Responsive layout automatic - -2. **✅ UserAdmin Popup Fix** - - Fixed popup forms to use Unfold templates - - Multiple inheritance: `class UserAdmin(BaseUserAdmin, ModelAdmin)` - - All popups now consistent with main admin styling - -3. **✅ Clean Architecture** - - Single admin system (Unfold only) - - No conflicts between themes - - All containers healthy - -4. **✅ CRITICAL: Sidebar Navigation Fix (Issue #5)** - - Custom sidebar now appears on ALL admin pages - - Consistent navigation throughout entire admin interface - - Fixed `get_app_list()` to ignore app_label parameter - - Set both `available_apps` and `app_list` in context - -5. **✅ Export Functionality** - - Added to 10+ critical models - - CSV/Excel export with proper Resource classes - - Account, Site, User, Payment, Keywords, Publishing, Sync Events all exportable - -6. **✅ Bulk Operations** - - Automation: Enable/disable configs - - Publishing: Retry failed publishes - - Integration: Enable/disable/trigger sync - - Content: Status changes, taxonomy assignment - - Tasks: Status changes, cluster assignment - - Keywords: Cluster assignment, status changes - ---- - -## Next Steps - -### Immediate (Current): -**Phase 5: Advanced Features** is the next phase to implement: -- Enable inline editing for Tasks and Keywords (list_editable) -- Add audit trail with django-simple-history to Payment, Account, CreditCostConfig -- Create admin permission groups for role-based access control - -### Implementation Ready: -All foundation work is complete (Phases 0-4). Phase 5 focuses on advanced admin features: -- **Inline Editing:** Quick edits without opening detail page -- **History Tracking:** Full audit trail for financial and account changes -- **Permission Groups:** Content Manager, Billing Admin, Support Agent roles - -### Operational Tasks (Ongoing): -1. Test reports with production data as system grows -2. Optimize slow report queries if needed -3. Review dashboard alerts weekly -4. Clean up old Celery task results monthly - ---- - -## Technical Notes - -- **No styling work required** - Unfold provides everything -- **Use Unfold classes** - badge, alert, card classes available -- **No emoji icons needed** - Unfold has Material Design icons -- **Focus on functionality** - UI is already handled - ---- - -## Resources - -- **Unfold Documentation:** https://unfoldadmin.com/ -- **Current Admin:** https://api.igny8.com/admin/ -- **Implementation Plan:** `/data/app/igny8/DJANGO-ADMIN-IMPROVEMENT-PLAN.md` diff --git a/docs/UX-METRICS-SYSTEM-PLAN.md b/docs/UX-METRICS-SYSTEM-PLAN.md new file mode 100644 index 00000000..61e8235c --- /dev/null +++ b/docs/UX-METRICS-SYSTEM-PLAN.md @@ -0,0 +1,420 @@ +# UX Metrics & Widget System - Strategic Plan + +## Document Purpose +Strategic plan for redesigning header metrics and footer widgets based on actual system architecture, workflow states, and user journey progression. No code - pure flow and implementation strategy. + +--- + +## Part 1: System Analysis & Current State + +### Data Models Status Tracking +**Keywords Model:** +- Status: `new` | `mapped` +- Cluster assignment: nullable FK +- Volume/difficulty: inherited from SeedKeyword or overridden +- Disabled flag: excludes from workflows + +**Clusters Model:** +- Status: `new` | `mapped` +- Keywords count: aggregated integer +- Total volume: summed from keywords +- Mapped pages: count of related content +- Disabled flag: workflow exclusion + +**ContentIdeas Model:** +- Status: `new` | `queued` | `completed` +- Cluster FK: optional relationship +- Keywords M2M: multi-keyword support +- Content type/structure: categorization +- Estimated word count: planning metric +- Disabled flag: workflow exclusion + +### Workflow Bottlenecks & State Transitions +**Critical Path Analysis:** +- Keywords without clusters = workflow blockage at Stage 1 +- Clusters without ideas = workflow blockage at Stage 2 +- Ideas not queued = manual intervention required at Stage 3 +- Volume data absence = prioritization impossible +- Disabled entities = silent workflow failures + +**Automation Dependencies:** +- Stage 1 requires minimum 5 keywords per batch +- Credit balance must exceed 1.2x estimated cost +- Site/sector filtering applied to all queries +- Lock mechanism prevents concurrent runs +- Partial results tracked per stage for resume capability + +--- + +## Part 2: Header Metrics Strategy (Top Banner) + +### Design Philosophy +Header metrics must communicate workflow readiness, not just data counts. Each metric should answer: "Can I progress to the next stage?" and "What's blocking me?" + +### Keywords Page Header Metrics + +**Metric 1: Pipeline Readiness Score** +- Formula: (clustered_keywords / total_active_keywords) × 100 +- Displays: percentage with contextual color coding +- Color logic: <30% red | 30-60% amber | 60-85% blue | >85% green +- Purpose: instant assessment of clustering progress +- User insight: "Am I ready for idea generation?" + +**Metric 2: Clustering Potential** +- Displays: count of `new` status keywords (unclustered) +- Secondary: estimated credits for auto-clustering +- Visibility trigger: shows when count > 5 (minimum batch size) +- Purpose: actionable metric for next AI operation +- User insight: "I have N keywords ready to cluster for X credits" + +**Metric 3: SEO Opportunity Index** +- Calculation: sum of volume for unclustered keywords with difficulty <3 +- Displays: total monthly search volume + count of "easy wins" +- Purpose: prioritization based on ROI potential +- User insight: "X monthly searches available in low-competition keywords" + +**Metric 4: Coverage Gaps** +- Logic: clusters with keywords_count = 1 (under-researched topics) +- Displays: count of thin clusters +- Secondary indicator: total volume in these clusters +- Purpose: highlight research needs before content creation +- User insight: "N clusters need more keyword research" + +**Metric 5: Automation Ready Status** +- Binary indicator: sufficient keywords for automation run +- Requirements checked: >5 keywords, credit balance adequate, no active lock +- Displays: checkmark icon + "Automation Ready" or blocking factor +- Purpose: remove friction for automation adoption +- User insight: Clear go/no-go for full pipeline run + +### Clusters Page Header Metrics + +**Metric 1: Content Generation Readiness** +- Formula: (clusters_with_ideas / total_active_clusters) × 100 +- Displays: percentage with progress indication +- Color coding: <40% red | 40-70% amber | 70-90% blue | >90% green +- Purpose: show how prepared user is for content creation +- User insight: "X% of my clusters are ready for content production" + +**Metric 2: Uncovered Clusters** +- Count: clusters with status=new AND ideas_count=0 +- Secondary: estimated credits for bulk idea generation +- Displays: "N clusters need ideas (cost: X credits)" +- Purpose: next-action clarity for AI operations +- User insight: Direct call-to-action with cost transparency + +**Metric 3: Total Coverage Volume** +- Calculation: sum of volume across all clusters +- Displays: formatted number (e.g., "24.5K monthly searches") +- Comparison: against previous period if available +- Purpose: show total market opportunity being addressed +- User insight: Scale of SEO opportunity in current cluster set + +**Metric 4: Cluster Health Score** +- Logic: percentage of clusters with keywords_count ≥3 AND volume >500 +- Displays: health percentage with quality indicator +- Purpose: surface clusters worth content investment +- User insight: "X% of clusters meet quality thresholds" + +**Metric 5: Mapped Content Progress** +- Count: clusters with mapped_pages >0 +- Ratio display: "X of Y clusters have published content" +- Purpose: track execution progress from planning to publication +- User insight: Content creation completion percentage + +### Ideas Page Header Metrics + +**Metric 1: Queue Activation Rate** +- Formula: (status=queued / total_ideas) × 100 +- Displays: percentage + absolute count of queued ideas +- Color: <20% amber | 20-50% blue | >50% green +- Purpose: measure activation momentum toward content creation +- User insight: "X ideas active in production queue" + +**Metric 2: Completion Velocity** +- Count: ideas with status=completed in current period +- Displays: completed count with trend indicator +- Purpose: show production throughput +- User insight: Content generation pace visibility + +**Metric 3: Content Credit Forecast** +- Calculation: sum of (estimated_word_count / 100) × content_generation_cost for new/queued ideas +- Displays: total credits needed for all pending ideas +- Comparison: against current credit balance +- Purpose: budget planning for content production +- User insight: "Production pipeline needs X credits (Y% of balance)" + +**Metric 4: Structure Distribution** +- Count: ideas grouped by content_structure (article, guide, listicle, etc.) +- Displays: most common structure + diversity score +- Purpose: content variety assessment +- User insight: Ensure diverse content mix for SEO + +**Metric 5: Orphaned Ideas Warning** +- Logic: ideas with no keyword_objects AND empty target_keywords +- Count display: number of ideas lacking keyword targeting +- Purpose: quality gate before queuing +- User insight: "X ideas need keyword assignment" + +--- + +## Part 3: Footer Widget System Design + +### Widget Philosophy +Footer widgets provide context-rich progress tracking and next-action guidance. Unlike header metrics (quick scan), footer widgets support deeper analysis and multi-metric relationships. + +### Keywords Page Footer Widgets + +**Widget 1: Workflow Progression Tracker** +- Display type: horizontal flow diagram with completion percentages +- Data points: Keywords → Clusters → Ideas → Tasks → Content +- Visual: connected nodes with percentage fills +- Interactive: clicking each node filters table to that state +- Purpose: visual pipeline status from keywords to final content +- Actionable insight: identify workflow bottlenecks visually + +**Widget 2: Clustering Efficiency Metrics** +- Card layout with 4 sub-metrics: + - Average keywords per cluster (target: 3-7) + - Cluster coverage ratio (clustered/total) + - Orphaned keywords count (no cluster assignment) + - Last clustering activity timestamp +- Purpose: measure clustering quality and recency +- Action trigger: "Run Auto-Cluster" button if efficiency low + +**Widget 3: SEO Opportunity Matrix** +- 2×2 grid visualization: Volume (high/low) × Difficulty (easy/hard) +- Four quadrants populated with keyword counts +- Color coding: high-volume + easy = green highlight +- Click behavior: filters table to quadrant keywords +- Purpose: prioritization dashboard for keyword targeting +- Strategic insight: focus efforts on high-ROI quadrants + +**Widget 4: Intent Distribution Breakdown** +- Pie chart or bar graph showing keyword counts by intent type +- Intent categories: informational, commercial, transactional, navigational +- Percentage display for each category +- Purpose: content strategy alignment check +- User insight: "Am I creating content for the right user intents?" + +### Clusters Page Footer Widgets + +**Widget 1: Cluster Maturity Dashboard** +- Table format with maturity scoring per cluster +- Columns: Cluster name | Keywords | Volume | Ideas | Content | Score +- Maturity score: weighted formula based on completeness +- Sort capability: by score, volume, or idea count +- Purpose: prioritize which clusters need attention +- Action: click to deep-dive into specific cluster + +**Widget 2: Content Pipeline Status** +- Progress bars for each active cluster showing: + - Ideas generated (vs target 3-5 per cluster) + - Tasks created (queued ideas) + - Content produced (completed articles) + - Published count (live on site) +- Purpose: track execution from planning to publication per cluster +- Visual hierarchy: clusters closest to completion highlighted + +**Widget 3: Volume vs Coverage Chart** +- Scatter plot: X-axis = total volume, Y-axis = content produced +- Each bubble = one cluster, size = keyword count +- Quadrant labels: "High opportunity, low coverage" = priority zone +- Purpose: visual gap analysis for content strategy +- Actionable: identify high-value clusters without content + +**Widget 4: Idea Generation Summary** +- Metrics card showing: + - Total clusters (active, not disabled) + - Clusters with 0 ideas (needs action) + - Average ideas per cluster + - Estimated credits to fill all gaps +- CTA button: "Generate Missing Ideas" with credit preview +- Purpose: one-click path to complete idea coverage + +### Ideas Page Footer Widgets + +**Widget 1: Production Queue Analytics** +- Three-column layout: + - New (not activated): count + bulk queue option + - Queued (in production): count + estimated completion time + - Completed: count + publish readiness indicator +- Progress bar: overall completion percentage across all ideas +- Purpose: production pipeline visibility and queue management +- Actions: bulk status updates with single click + +**Widget 2: Content Type Mix Analyzer** +- Stacked bar chart showing distribution: + - Content types: post, page, product, taxonomy + - Structure types: article, guide, comparison, review, listicle +- Target mix overlay: recommended distribution for SEO +- Purpose: ensure content portfolio diversity +- Insight: flag over-concentration in single content type + +**Widget 3: Keyword Targeting Health** +- Metrics showing: + - Ideas with 0 keywords (critical issue) + - Ideas with 1-2 keywords (acceptable) + - Ideas with 3+ keywords (optimal) + - Average keyword count per idea +- Alert: red badge for ideas missing keywords +- Purpose: quality control before content production +- Action: filter table to show untargeted ideas + +**Widget 4: Credit Burn Rate Projector** +- Financial planning widget: + - Current queued ideas credit cost + - Current credit balance + - Estimated credits per week based on queue rate + - Runway: weeks until credits depleted at current pace +- Visual: gauge showing balance sufficiency +- Purpose: prevent mid-production credit depletion +- Action: "Add Credits" CTA when runway <2 weeks + +--- + +## Part 4: Cross-Page Integration Strategy + +### Global Workflow State Indicator +- Persistent mini-widget in page header showing: + - Current stage completion: Keywords 85% → Clusters 60% → Ideas 40% + - Next recommended action based on lowest percentage + - Quick-jump links to pages needing attention +- Purpose: maintain workflow context across navigation +- Always visible: helps users stay oriented in multi-step process + +### Automation Readiness Badge +- Displayed when ALL conditions met: + - Keywords ≥5 per batch configuration + - Credit balance ≥ 1.2× estimated pipeline cost + - No active automation lock + - At least one complete keyword→cluster→idea chain exists +- Visual: pulsing badge "Ready for Automation" +- Click behavior: opens automation config modal +- Purpose: drive automation adoption at optimal timing + +--- + +## Part 5: Implementation Data Requirements + +### New Computed Fields Needed +**Keywords Model:** +- Pipeline position: enum tracking how far keyword has progressed +- SEO opportunity score: volume × (inverse difficulty) calculation +- Last modified timestamp: for activity recency metrics + +**Clusters Model:** +- Maturity score: formula based on keywords count, ideas count, volume, content count +- Completion percentage: ideas/target ratio +- Health status: enum (healthy, needs-attention, critical) + +**ContentIdeas Model:** +- Production readiness: boolean check for keywords, structure, word count +- Estimated time to complete: based on word count and average production rate +- Target ROI: volume of associated keywords / estimated credits + +### Aggregation Queries Required +- Cross-model counts: keywords→clusters→ideas→tasks→content chain +- Volume summations: at keyword, cluster, and idea levels with filtering +- Credit calculations: bulk cost estimates for batch operations +- Time-series data: completion rates over rolling periods +- Distribution analyses: intent, difficulty, structure breakdowns + +### Performance Considerations +- Cache frequently accessed aggregations (cluster counts, volume sums) +- Compute expensive metrics asynchronously (maturity scores, opportunity indices) +- Provide real-time updates only for user-initiated actions +- Use database views for complex joins in footer widgets +- Implement pagination for widget data exceeding 100 records + +--- + +## Part 6: User Journey Mapping + +### New User Journey (Days 1-7) +**Day 1:** Import keywords → Header shows "0% clustered" → Footer widget highlights "Run Auto-Cluster" +**Day 2:** Keywords clustered → Header shows improvement → Footer suggests "Generate ideas for X clusters" +**Day 3:** Ideas created → Header shows queue status → Footer prompts "Queue ideas to Writer" +**Day 5:** First content in production → All metrics show progress → Automation badge appears +**Day 7:** First publish → Footer celebrates milestone → Prompts scaling via automation + +### Established User Journey (Ongoing) +- Header metrics: quick health check on page load +- Footer widgets: deep-dive when planning next actions +- Automation badge: reinforces scale-up path +- Cross-page indicator: maintains context during workflow execution + +### Power User Journey (Optimization Phase) +- Header metrics: track efficiency improvements (better clustering ratios, higher completion rates) +- Footer widgets: strategic planning tools (opportunity matrices, ROI projections) +- Automation: primary workflow with manual intervention only for edge cases + +--- + +## Part 7: Accessibility & Responsiveness + +### Mobile Considerations +- Header metrics: show top 3 most critical on mobile, expandable drawer for rest +- Footer widgets: vertical stack layout, one widget visible at a time with swipe navigation +- Touch targets: minimum 44×44px for all interactive elements +- Tooltip alternatives: tap-to-reveal detail panels instead of hover states + +### Screen Reader Support +- Semantic HTML: use proper ARIA landmarks for metric regions +- Live regions: announce metric updates with aria-live for dynamic changes +- Descriptive labels: "Pipeline readiness 67 percent, requires attention" vs "67%" +- Keyboard navigation: tab order follows logical workflow progression + +### Color Blindness Accommodations +- Pattern overlays: combine color with icons or patterns (not color alone) +- High contrast mode: ensure metrics readable in Windows high contrast +- Text labels: always include text with color-coded indicators +- Consistent semantics: green=good, red=needs action, amber=caution across all contexts + +--- + +## Part 8: Success Metrics for This System + +### Engagement Metrics +- Metric interaction rate: percentage of users clicking header metrics or footer widgets +- Action completion: users who click widget CTA and complete suggested action +- Navigation patterns: reduced page-hopping after metrics implementation +- Time-to-action: reduced time from page load to workflow action initiation + +### Business Impact Metrics +- Automation adoption: percentage increase in users running automation after readiness badge +- Credit efficiency: credits spent per published article (should decrease with better planning) +- Pipeline velocity: reduced time from keyword import to content publication +- User retention: reduced churn in days 3-14 (critical onboarding period) + +### Quality Metrics +- Fewer orphaned keywords: percentage of keywords clustered increases +- Better keyword targeting: ideas with 0 keywords decreases +- Content diversity: even distribution across content structures +- Credit planning: fewer instances of mid-production credit depletion + +--- + +## Part 9: Future Enhancement Considerations + +### Predictive Metrics +- ML-based opportunity scoring: predict which clusters will generate most traffic +- Credit burn forecasting: predict when user will need to purchase more credits +- Completion time estimates: based on historical user patterns and queue depth +- Anomaly detection: alert when metrics deviate significantly from user's baseline + +### Comparative Metrics +- Benchmark against similar accounts: "Your clustering efficiency is in top 20%" +- Historical comparison: "30% improvement in pipeline velocity vs last month" +- Goal tracking: user-set targets with progress indicators +- Peer insights: anonymized aggregate data showing what successful users do + +### Integration Opportunities +- Export metrics to external analytics: Google Data Studio, Tableau +- Webhook notifications: alert external systems when key thresholds crossed +- API access: allow users to build custom dashboards with metric data +- Calendar integration: suggest optimal times to run automation based on credit refresh + +--- + +*End of Strategic Plan - Ready for implementation phase with component-level specifications*