diff --git a/docs/plans/4th-jan-refactor/final-model-schemas.md b/docs/90-REFERENCE/final-model-schemas.md similarity index 100% rename from docs/plans/4th-jan-refactor/final-model-schemas.md rename to docs/90-REFERENCE/final-model-schemas.md diff --git a/docs/FILTER_GUIDELINES.md b/docs/FILTER_GUIDELINES.md deleted file mode 100644 index bb153d79..00000000 --- a/docs/FILTER_GUIDELINES.md +++ /dev/null @@ -1,168 +0,0 @@ -# Filter Implementation Guidelines - -## Core Principles - -### 1. Dynamic Filter Options (Cascading Filters) -Filters should **ALWAYS** load their options from the backend based on **actual data in the current filtered result set**. - -**Why?** -- Prevents showing filter values that would return 0 results -- Ensures filters only show what exists in the current data context -- Provides better UX - users see only relevant choices - -### 2. Backend filter_options Endpoint Pattern -Each module's ViewSet should have a `filter_options` action that: -- Returns distinct values from actual data -- Prepends "All X" option for each filter type -- Supports cascading (applying other filters when calculating each option list) - -```python -@action(detail=False, methods=['get'], url_path='filter_options') -def filter_options(self, request): - """ - Returns distinct filter values from ACTUAL DATA in the queryset. - Supports cascading - each filter's options exclude itself but apply other filters. - Backend ALWAYS prepends the "All X" option. - """ - queryset = self.get_queryset() - - # Get current filter values - status_filter = request.query_params.get('status', '') - type_filter = request.query_params.get('content_type', '') - - # For each filter option, apply OTHER filters (not self) - type_qs = queryset - if status_filter: - type_qs = type_qs.filter(status=status_filter) - - content_types = list(set(type_qs.values_list('content_type', flat=True))) - content_types = sorted([t for t in content_types if t]) - - # BACKEND prepends "All" option - content_type_options = [ - {'value': '', 'label': 'All Types'}, - ] + [ - {'value': t, 'label': TYPE_LABELS.get(t, t.title())} - for t in content_types - ] - - return success_response(data={'content_types': content_type_options}) -``` - -### 3. Frontend Filter Config Pattern -Frontend configs should use dynamic options **DIRECTLY** without adding "All" prefix: - -```typescript -// CORRECT - Backend already includes "All Types" option -filters: [ - { - key: 'content_type', - label: 'Type', - type: 'select', - options: handlers.contentTypeOptions, // Use directly from backend - }, -] - -// WRONG - Don't add "All" in frontend (causes duplicates) -options: [ - { value: '', label: 'All Types' }, // DON'T DO THIS - ...(handlers.contentTypeOptions || []), -] -``` - -### 4. Page-Specific Base Constraints -Pages with fixed default filters should pass constraints when loading filter_options: - -```typescript -// APPROVED PAGE - only show filters for approved/published content -const loadFilterOptions = useCallback(async (currentFilters) => { - const options = await fetchWriterContentFilterOptions(activeSite.id, { - ...currentFilters, - status__in: 'approved,published', // Base constraint - }); - setStatusOptions(options.statuses || []); -}, [activeSite]); - -// DRAFTS PAGE - only show filters for draft content -const loadFilterOptions = useCallback(async (currentFilters) => { - const options = await fetchWriterContentFilterOptions(activeSite.id, { - ...currentFilters, - status: 'draft', // Base constraint - }); - setContentTypeOptions(options.content_types || []); -}, [activeSite]); -``` - -### 5. Clear Filters Button -Every page with filters should provide `onFilterReset` handler: - -```typescript - { /* ... */ }} - onFilterReset={() => { - setSearchTerm(''); - setContentTypeFilter(''); - setCurrentPage(1); - }} -/> -``` - -### 6. Filter Dependencies -Ensure filter state variables are in useCallback dependency arrays: - -```typescript -// CORRECT - all filter states in dependencies -const loadContent = useCallback(async () => { - const filters = { - status: statusFilter, - content_type: contentTypeFilter, - }; - // ... -}, [statusFilter, contentTypeFilter, /* other deps */]); - -// WRONG - missing filter in dependencies (filter won't trigger reload) -}, [statusFilter]); // Missing contentTypeFilter! -``` - -### 7. What NOT to Do - -❌ **Don't add "All X" prefix in frontend config (backend does it):** -```typescript -// BAD - causes duplicate "All Types" entries -options: [ - { value: '', label: 'All Types' }, - ...(handlers.contentTypeOptions || []), -] -``` - -❌ **Don't forget filter state in useCallback dependencies:** -```typescript -// BAD - contentStatusFilter changes won't reload data -}, [statusFilter, sortBy, searchTerm]); // Missing contentStatusFilter -``` - -❌ **Don't forget onFilterReset handler:** -```typescript -// BAD - no Clear button will show - -``` - -## Implementation Checklist - -For each page with filters: - -- [ ] Backend `filter_options` prepends "All X" option for each filter type -- [ ] Backend applies cascading logic (each filter excludes itself) -- [ ] Frontend config uses `handlers.xxxOptions` directly (no "All" prefix) -- [ ] Page passes base constraints (e.g., status='draft') to filter_options -- [ ] Page provides `onFilterReset` handler to TablePageTemplate -- [ ] All filter states are in useCallback/useEffect dependencies -- [ ] Filter values in filterValues object match filter keys in config diff --git a/docs/plans/Future_Moduels_Features/Content_Types_Writing_Plan.md b/docs/plans/Future_Moduels_Features/Content_Types_Writing_Plan.md new file mode 100644 index 00000000..eb840c1d --- /dev/null +++ b/docs/plans/Future_Moduels_Features/Content_Types_Writing_Plan.md @@ -0,0 +1,156 @@ +# Content Types Writing Plan (Detailed) + +**Goal:** Make IGNY8 capable of **writing content for multiple post types** (pages, products, services, company pages, taxonomy terms) using the **same Planner → Ideas → Tasks → Writer → Images** workflow as posts. + +**Scope:** WordPress-only for current release. Shopify/custom support is future. + +--- + +## 1) Core Principle +All content types follow the **same pipeline**: + +``` +Clusters → Ideas → Tasks → Content → Images → Review → Publish +``` + +Differences are handled by **content_type** and **content_structure** presets, plus targeted prompts and schema. + +--- + +## 2) Content Types & Structures + +### 2.1 Pages (Static) +- **content_type:** `page` +- **content_structure:** `landing_page`, `business_page`, `general` +- **Use cases:** About, Contact, FAQs, Pillar landing pages + +### 2.2 Products (Custom Post Type) +- **content_type:** `product` +- **content_structure:** `product_page` +- **Use cases:** Individual products or product collections + +### 2.3 Services (Custom Post Type) +- **content_type:** `service` +- **content_structure:** `service_page` +- **Use cases:** Service offering pages, location variants + +### 2.4 Company Pages +- **content_type:** `page` +- **content_structure:** `business_page` or `general` +- **Use cases:** Team, Careers, Press, Mission + +### 2.5 Taxonomy Terms (Landing Pages) +- **content_type:** `taxonomy` +- **content_structure:** `category_archive`, `tag_archive`, `attribute_archive`, `cluster_hub` +- **Use cases:** Category/tag/attribute landing pages with SEO content + +--- + +## 3) Pipeline Mapping (Same as Posts) + +### 3.1 Clusters → Ideas +- Each cluster generates ideas **per content type** based on intent. +- Example: one cluster may yield a page, a product page, and a service page idea. + +### 3.2 Ideas → Tasks +- `Tasks` created with `content_type` and `content_structure`. +- Taxonomy terms can create tasks tied to `taxonomy_term`. + +### 3.3 Tasks → Content +- Writer uses existing prompt system with type-specific prompts. +- Outputs HTML + meta title + meta description + structure. + +### 3.4 Content → Images +- Uses existing image pipeline (featured + in‑article). +- Products/services can add attribute-based prompts. + +--- + +## 4) WordPress Integration (Current Scope) + +### 4.1 Post Types +- `post`, `page`, custom post types (`product`, `service`) + +### 4.2 Taxonomies +- `category`, `post_tag`, `product_cat`, `product_tag` +- WooCommerce attributes (e.g., `pa_color`, `pa_size`) + +--- + +## 5) Writing Rules per Content Type + +### 5.1 Pages +- Clear CTA and conversion focus. +- Structured sections for trust + proof. + +### 5.2 Products +- Feature/benefit sections, specs table, FAQs. +- Product schema + review snippets. + +### 5.3 Services +- Service overview, process steps, outcomes, FAQs. +- Local SEO sections if location-based. + +### 5.4 Company Pages +- Brand mission, values, history, team bios. +- FAQ and media/press block where relevant. + +### 5.5 Taxonomy Landing Pages +- Intro + topical definition +- Key subtopics + internal links +- Related products/posts/services +- FAQ section + +--- + +## 6) Cluster Alignment +- Each page is mapped to a **primary cluster**. +- Secondary clusters used for semantic coverage. +- Cluster keywords drive headings and metadata. + +--- + +## 7) Required Enhancements + +### 7.1 Ideas Generation +- Add type-specific idea templates: + - Product ideas (features/specs/benefits) + - Service ideas (process/outcomes) + - Company page ideas (mission/team/careers) + - Term landing ideas (taxonomy descriptions) + +### 7.2 Writer Prompts +- Add prompt variants for each `content_structure`. + +### 7.3 Publishing +- Map content types to WordPress post types correctly. +- Taxonomy landing pages publish to term descriptions or custom fields. + +--- + +## 8) Rollout Phases + +**Phase 1** +- Pages + services + company pages in Writer +- Task creation with new structures + +**Phase 2** +- Products pages writing (WooCommerce) +- Attribute-based prompts + +**Phase 3** +- Taxonomy landing pages +- Cluster hub pages + +--- + +## 9) Success Criteria +- All content types generated via same pipeline. +- Cluster alignment across all page types. +- Improved SEO coverage beyond posts. + +--- + +## 10) Non‑Goals (v1) +- Shopify/custom CMS adapters +- Auto‑publish without review diff --git a/docs/plans/Future_Moduels_Features/FB_LinkedIn_Auth_flow_Steps.md b/docs/plans/Future_Moduels_Features/FB_LinkedIn_Auth_flow_Steps.md new file mode 100644 index 00000000..91a61828 --- /dev/null +++ b/docs/plans/Future_Moduels_Features/FB_LinkedIn_Auth_flow_Steps.md @@ -0,0 +1,210 @@ +## IGNY8 Socializer Module - Development Flow + +--- + +### 1. Meta (Facebook) Setup + +**One-time Config:** +- Create Business App at developers.facebook.com +- Add Facebook Login + Pages API products +- Set redirect URI: `https://igny8.com/auth/facebook/callback` +- Request permissions: `pages_manage_posts`, `pages_read_engagement`, `publish_to_groups` +- Submit for App Review (required for production) + +**What to Build:** + +| Component | Details | +|-----------|---------| +| Connect Button | Triggers OAuth, stores long-lived user token + page tokens | +| Account Picker | After auth, user selects which Pages/Groups to enable | +| Token Refresh Job | Cron to refresh tokens before 60-day expiry | +| Post Service | Accepts content + destination, calls `/{page-id}/feed` | +| Webhook Listener | Optional: receive post status updates | + +**Posting Capabilities:** +- ✅ Pages (as Page) +- ⚠️ Groups (limited, user must be admin, needs approval) +- ❌ Personal profiles (blocked by Meta) + +--- + +### 2. LinkedIn Setup + +**One-time Config:** +- Create App at linkedin.com/developers +- Verify/associate with a Company Page +- Request products: "Share on LinkedIn", "Marketing Developer Platform" (for org posting) +- Set redirect URI: `https://igny8.com/auth/linkedin/callback` +- Permissions: `w_member_social`, `w_organization_social`, `r_liteprofile`, `r_organization_social` + +**What to Build:** + +| Component | Details | +|-----------|---------| +| Connect Button | OAuth flow, store access token + refresh token | +| Account Picker | User selects personal profile and/or Company Pages they admin | +| Token Refresh Job | Use refresh token before 60-day expiry | +| Post Service | Calls `/rest/posts` with author URN (person or organization) | +| URN Storage | Store `urn:li:person:{id}` and `urn:li:organization:{id}` per account | + +**Posting Capabilities:** +- ✅ Personal profile +- ✅ Company Pages (user must be admin) +- ❌ Groups (no API) + +--- + +### 3. Database Schema (additions) + +``` +SocialAccount +├── user (FK to IGNY8 user) +├── platform (facebook | linkedin) +├── platform_user_id +├── access_token (encrypted) +├── refresh_token (encrypted, LinkedIn only) +├── token_expires_at +├── scopes_granted +├── created_at / updated_at + +SocialDestination +├── social_account (FK) +├── destination_type (page | group | profile | company) +├── destination_id (platform's ID) +├── destination_name +├── is_active +├── permissions_valid + +SocialPost +├── site (FK to user's IGNY8 site) +├── content_source (FK to generated content) +├── destination (FK to SocialDestination) +├── platform_post_id +├── status (pending | posted | failed) +├── posted_at +├── error_message +``` + +--- + +### 4. Backend Services + +| Service | Purpose | +|---------|---------| +| `SocialAuthService` | Handle OAuth callbacks, token exchange, storage | +| `TokenRefreshService` | Scheduled job to refresh expiring tokens | +| `DestinationSyncService` | After auth, fetch and store available pages/groups/companies | +| `SocialPublisherService` | Generic interface → platform-specific posting logic | +| `PostQueueWorker` | Process scheduled social posts from queue | + +--- + +### 5. Frontend Components + +| Component | Purpose | +|-----------|---------| +| Social Connections Page | List connected accounts, connect/disconnect buttons | +| Destination Selector | Per-site config: which destinations receive auto-posts | +| Post Preview Modal | Before posting: preview how content appears | +| Post History Table | Show status of all social posts per site | +| Settings per Destination | Customize format, hashtags, include link, image behavior | + +--- + +### 6. Content-to-Social Flow + +``` +Content Published to WP + ↓ +Check site's social destinations (active ones) + ↓ +For each destination: + → Format content (title, excerpt, link, image) + → Apply destination-specific template + → Queue SocialPost record + ↓ +PostQueueWorker picks up + ↓ +Call platform API → update status → log result +``` + +--- + +### 7. Post Formatting Options (per destination) + +- Post template: `{title}\n\n{excerpt}\n\nRead more: {url}` +- Include featured image: yes/no +- Auto-hashtags from keywords +- Character limit handling (LinkedIn: 3000, Facebook: 63,206) +- Link preview behavior + +--- + +### 8. Error Handling + +- Token expired → mark account as needs reconnection, notify user +- Rate limited → exponential backoff retry +- Permission revoked → disable destination, notify user +- API error → log, retry up to 3x, then mark failed + +--- +--- + +## Rate Limits & User Limits + +--- + +### Facebook/Meta + +**No limit on number of users/pages/groups** connecting to your single app. + +**But there are API call limits:** + +| Limit Type | Details | +|------------|---------| +| App-level | 200 calls/user/hour baseline, scales with active users | +| Page posting | ~25 posts/page/day (soft limit, not documented hard cap) | +| Groups | Much stricter, ~5-10 posts/day/group to avoid spam flags | +| Burst protection | Too many calls in short time = temporary throttle | + +**Scaling factor:** Your app's call limit increases automatically as more users connect (more users = higher pool). + +--- + +### LinkedIn + +**No limit on users/companies** connecting. + +**API limits:** + +| Limit Type | Details | +|------------|---------| +| Daily app limit | 100,000 calls/day (standard tier) | +| Per-user posting | ~100-150 posts/day/member (undocumented soft limit) | +| Company pages | ~100 posts/day/org | +| Rate limit | 100 requests/minute per user token | + +**Marketing Developer Platform** (if approved): Higher limits for company page management. + +--- + +### Practical Concerns + +| Concern | Reality | +|---------|---------| +| 100 IGNY8 users, each with 2 pages | No problem at all | +| 1000 users, each with 5 pages | Still fine, monitor call volume | +| Spam behavior | Biggest risk - platforms will flag/ban aggressive posting | + +--- + +### Recommendations for IGNY8 + +1. **Implement per-destination cooldowns** - minimum 4-6 hours between posts to same page/group +2. **Track API usage** - log calls, alert if approaching limits +3. **Queue with spreading** - don't burst 50 posts at once, spread across hours +4. **User-level limits** - cap posts/day per destination in your own system + +--- + +No licensing fees or per-seat costs from Meta/LinkedIn for API access itself. Just respect the rate limits and avoid spammy patterns. \ No newline at end of file diff --git a/docs/plans/Future_Moduels_Features/GSC_plnning_to_be_updated_consistent_with_supported_API_and_Igny8_app.md b/docs/plans/Future_Moduels_Features/GSC_plnning_to_be_updated_consistent_with_supported_API_and_Igny8_app.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/plans/Future_Moduels_Features/Linker_Module_Plan.md b/docs/plans/Future_Moduels_Features/Linker_Module_Plan.md new file mode 100644 index 00000000..3ad32158 --- /dev/null +++ b/docs/plans/Future_Moduels_Features/Linker_Module_Plan.md @@ -0,0 +1,264 @@ +# Linker Module Plan (Detailed) + +**Scope:** Current implementation is **WordPress-only** for publishing/sync and content discovery. The design supports future Shopify and custom sites but is **not enabled** for them in v1. + +**Status Today:** Linker module exists but is inactive by default and not fully protected by feature flags. See [docs/10-MODULES/LINKER.md](../../10-MODULES/LINKER.md). + +--- + +## 1) Goal +Enable AI-driven internal and external linking for all content types that IGNY8 manages or syncs, while staying consistent with the existing pipeline and settings architecture. + +**Primary objectives:** +- Increase topical authority via strategic internal linking (posts, pages, taxonomy pages, cluster pages, products, services). +- Improve UX and SEO through better anchor placement and link coverage. +- Maintain link hygiene with ongoing link health monitoring. +- Support outbound linking to authoritative sources with relevance scoring. +- Provide a pathway for **backlink discovery** (informational only in v1, no outreach automation). + +--- + +## 2) Feature Set (Detailed) + +### 2.1 Internal Linking (Core) +**What it does** +- Suggests internal links for content based on keyword clusters, topic similarity, and taxonomy alignment. + +**Targets supported** +- Posts +- Pages +- Taxonomy archives (category/tag) +- Cluster pages (IGNY8-defined topical clusters) +- Product pages *(WordPress product CPT if present; Shopify later)* +- Service pages *(custom post types if configured)* + +**Anchor strategies** +- Exact match +- Partial match +- Semantic match +- Brand-safe anchor constraints (from site-level settings) + +**Controls** +- Max links per content item +- Per-section link density caps +- Avoid repeated anchors +- Exclude URLs or content statuses (draft, private) + +--- + +### 2.2 External Linking (Authority Sources) +**What it does** +- Recommends outbound links to reputable domains relevant to content topic. + +**Constraints** +- Domain whitelist/blacklist +- Authority threshold (DR/DA proxy) +- No competitor domains (configurable) +- Link type: dofollow/nofollow + +--- + +### 2.3 Backlink Discovery (Read-only in v1) +**What it does** +- Lists relevant external sites that are topically related for future outreach. + +**Notes** +- No automated outreach in v1. +- Future: integrate with email/outreach tools. + +--- + +### 2.4 Link Health & Monitoring +**What it does** +- Detects broken internal/external links. +- Tracks link status and changes. + +**Actions** +- Flag broken links +- Suggest replacements +- Quick-fix internal links + +--- + +### 2.5 Automation & Pipeline Integration +**What it does** +- Can run after Writer stage to enrich IGNY8-generated content. +- Can run on synced WordPress content. + +**Modes** +- Manual: per content item +- Batch: selected items +- Automation stage: optional in automation pipeline + +--- + +## 3) App-Consistent Architecture + +### 3.1 Backend Modules (Aligned with Current Structure) +- Existing: `backend/igny8_core/modules/linker/` +- Existing: `backend/igny8_core/business/content/services/content_pipeline_service.py` + +**Add / Extend** +- `business/linker/` (services, scoring, health checks) +- `modules/linker/models.py` (link suggestions, health checks) +- `modules/linker/serializers.py` +- `modules/linker/views.py` (extend API) + +--- + +### 3.2 Data Models (Proposed) + +**LinkSuggestion** +- `account`, `site`, `content` +- `anchor_text`, `anchor_strategy` +- `target_url`, `target_content_id` (nullable for external) +- `target_type` (internal/external/taxonomy/cluster/product/service) +- `confidence_score` +- `status` (suggested/applied/rejected) +- `metadata` (keyword match, similarity score) + +**LinkHealthStatus** +- `site`, `url`, `status_code`, `last_checked_at`, `is_broken` + +**ExternalSourceCandidate** +- `topic`, `domain`, `url`, `authority_score`, `relevance_score` + +--- + +### 3.3 API Endpoints (Aligned with Existing Style) + +**Existing** +- `POST /api/v1/linker/process/` +- `POST /api/v1/linker/batch_process/` + +**Add** +- `GET /api/v1/linker/suggestions/?content_id=` +- `POST /api/v1/linker/apply/` +- `POST /api/v1/linker/reject/` +- `POST /api/v1/linker/health/scan/` +- `GET /api/v1/linker/health/status/?site_id=` +- `GET /api/v1/linker/external-sources/?content_id=` + +--- + +### 3.4 Frontend Pages (Consistent with Current UI) + +**Pages** +- `/linker/content` (list content + status + batch actions) +- `/linker/content/:id` (link suggestions + apply) + +**Components** +- Suggestions table +- Inline preview with anchor highlights +- Link health panel +- External sources panel + +--- + +## 4) WordPress-Only Scope (Current Release) + +### 4.1 WordPress Content Types +- Posts +- Pages +- Categories / Tags (taxonomy archives) +- Custom post types (products/services) if configured in integration + +### 4.2 WordPress Sync Integration +- Leverage existing sync flows to ingest WordPress content and taxonomies. +- Maintain `wordpress_id` mapping for internal link targeting. + +--- + +## 5) Linking Logic (High-Level) + +### 5.1 Internal Link Discovery +- Cluster overlap +- Keyword match to title + headers +- Taxonomy match (category/tag) +- Content type compatibility + +### 5.2 External Link Discovery +- Use curated sources or internal dataset +- Score by relevance + authority + +### 5.3 Anchor Placement +- Avoid headings and existing links +- Prefer first 60% of content +- Cap per section + +--- + +## 6) Settings & Controls (Unified Settings) + +**Site Settings → Automation tab** +- Enable Linker module +- Max internal links per content +- Max external links per content +- Target link density +- Excluded URLs / domains +- Anchor text rules + +--- + +## 7) Notifications +- “Link suggestions ready” +- “Links applied” +- “Broken links detected” + +--- + +## 8) Rollout Phases + +**Phase 1 (MVP)** +- Internal links + anchor suggestions +- Manual apply +- Content-level preview + +**Phase 2** +- External link suggestions +- Batch processing + +**Phase 3** +- Link health scanning +- Automation stage support + +**Phase 4** +- Backlink discovery (read-only) + +--- + +## 9) Non-Goals (v1) +- Automated outreach +- Paid backlink acquisition +- Shopify support (future) +- Custom CMS adapters (future) + +--- + +## 10) Success Criteria +- Increased internal link coverage per content piece +- Reduced orphaned content +- Improved ranking on linked clusters +- Minimal false-positive link placements + +--- + +## 11) Dependencies +- Content metadata quality (keywords, clusters, taxonomies) +- WordPress integration sync health +- Automation settings availability + +--- + +## 12) Risks & Mitigations +- **Risk:** Over-linking → **Mitigation:** enforce density caps and editor review. +- **Risk:** Bad anchors → **Mitigation:** anchor validation + manual approval. +- **Risk:** Broken external links → **Mitigation:** link health checks + replacements. + +--- + +## 13) Future Extensions (Post‑WordPress) +- Shopify product catalogs +- Custom CMS content ingestion +- Cross-domain linking for multi-brand portfolios +- Outreach workflows for backlink acquisition diff --git a/docs/plans/Future_Moduels_Features/Optimizer_Module_Plan.md b/docs/plans/Future_Moduels_Features/Optimizer_Module_Plan.md new file mode 100644 index 00000000..a16b1619 --- /dev/null +++ b/docs/plans/Future_Moduels_Features/Optimizer_Module_Plan.md @@ -0,0 +1,235 @@ +# Optimizer Module Plan (Detailed) + +**Scope:** Optimizer focuses on **rewriting/optimizing existing content** across posts, pages, products, services, company pages, and taxonomy archives. Current release scope is **WordPress-only** (publish/sync + content discovery). Shopify/custom support is future. + +**Status Today:** Optimizer module exists but is inactive by default and partially implemented. See [docs/10-MODULES/OPTIMIZER.md](../../10-MODULES/OPTIMIZER.md). + +--- + +## 1) Goal +Upgrade existing content to SEO‑strong, intent‑aligned pages by: +- Mapping content to **semantic/topic clusters**. +- Aligning page intent with cluster keyword targets. +- Rewriting structure + content to match current search intent. +- Adding schema, metadata, and on‑page SEO improvements. + +--- + +## 2) Feature Set (Detailed) + +### 2.1 Content Types Supported (WordPress v1) +- Posts (blog/article) +- Pages (static) +- Products (custom post type, if configured) +- Services (custom post type, if configured) +- Company pages (about/team/careers/FAQ/press) +- Taxonomy archives (category/tag) +- Cluster pages (IGNY8 cluster views) + +--- + +### 2.2 Cluster‑Aligned Optimization +**What it does** +- Associates each content item with a **primary cluster** + secondary clusters. +- Uses cluster keyword list as optimization targets. + +**Outputs** +- Updated content aligned to the best matching cluster intent. +- Keyword coverage improvements with semantic variants. + +--- + +### 2.3 Intent‑Aligned Rewrite Engine +**What it does** +- Rewrites content to match user intent (informational, commercial, transactional). +- Adjusts structure and sections to meet SERP expectations. + +**Capabilities** +- Expand thin pages into full SEO pages. +- Compress overly long pages to reduce fluff. +- Add missing sections and re‑order content flow. + +--- + +### 2.4 SEO‑Rich Output (Structure + Meta + Schema) +**What it does** +- Generates SEO‑optimized headings, internal structure, and metadata. +- Adds schema markup when applicable. + +**Includes** +- Meta title + meta description refresh +- H1/H2/H3 structure alignment +- Internal/external link placeholders (Linker integration) +- Image alt text improvements +- Schema JSON‑LD (Article, Product, FAQ, Organization, Breadcrumb, Service) + +--- + +### 2.5 Page‑Level Optimization Scores +**What it does** +- Scores before/after content quality using current Optimizer scoring model. +- Tracks improvements by cluster alignment + keyword coverage. + +--- + +## 3) App‑Consistent Architecture + +### 3.1 Backend Modules (Aligned with Current Structure) +- Existing: `backend/igny8_core/modules/optimizer/` +- Existing: `backend/igny8_core/business/optimization/` + +**Add / Extend** +- `business/optimization/cluster_mapping.py` (cluster assignment & keyword targets) +- `modules/optimizer/models.py` (extend OptimizationTask) +- `modules/optimizer/serializers.py` (add cluster mapping + schema) +- `modules/optimizer/views.py` (extend API) + +--- + +### 3.2 Data Models (Proposed Extensions) + +**OptimizationTask** (extend) +- `primary_cluster_id` +- `secondary_cluster_ids` (JSON) +- `keyword_targets` (JSON) +- `schema_type` (article/product/service/faq/org) +- `schema_json` (JSON) +- `metadata_before` (JSON) +- `metadata_after` (JSON) +- `structure_changes` (JSON) + +--- + +### 3.3 API Endpoints (Aligned with Existing Style) + +**Existing** +- `POST /api/v1/optimizer/analyze/` +- `POST /api/v1/optimizer/optimize/` +- `POST /api/v1/optimizer/batch_optimize/` + +**Add** +- `POST /api/v1/optimizer/assign_cluster/` +- `GET /api/v1/optimizer/cluster_suggestions/?content_id=` +- `POST /api/v1/optimizer/preview/` (structure + metadata + schema preview) +- `POST /api/v1/optimizer/apply/` (persist optimized version) + +--- + +### 3.4 Frontend Pages (Consistent with Current UI) + +**Pages** +- `/optimizer/content` (content list + status) +- `/optimizer/preview/:id` (analysis + diff + schema preview) + +**Components** +- Cluster mapping panel +- Keyword target editor +- Structure diff viewer +- Metadata + schema preview + +--- + +## 4) WordPress‑Only Scope (Current Release) + +### 4.1 WordPress Content Coverage +- Posts and Pages +- Taxonomy archives (category/tag) +- Custom post types (products/services if configured) + +### 4.2 WordPress Sync Integration +- Use existing sync pipelines to pull WordPress content. +- Maintain `wordpress_id` mapping for optimized updates. + +--- + +## 5) Optimization Logic (High‑Level) + +### 5.1 Cluster Matching +- Analyze content title, headings, and keyword density. +- Match to existing cluster keyword sets. +- Provide suggestions if confidence < threshold. + +### 5.2 Content Rewrite +- Rebuild structure to match intent + cluster focus. +- Inject missing sections (FAQs, comparisons, benefits, use cases). +- Normalize tone with existing Writer prompt settings. + +### 5.3 SEO Enhancements +- Meta title/description refresh +- Heading structure refinement +- Internal link opportunities (handoff to Linker) +- Schema generation based on content type + +--- + +## 6) Settings & Controls (Unified Settings) + +**Site Settings → Automation tab** +- Enable Optimizer module +- Default schema type per content type +- Keyword density targets +- Content length guidelines +- Allow auto‑apply vs manual review + +--- + +## 7) Notifications +- “Optimization analysis ready” +- “Optimization applied” +- “Schema generated” + +--- + +## 8) Rollout Phases + +**Phase 1 (MVP)** +- Analyze + optimize existing posts/pages +- Cluster mapping suggestions +- Manual apply + +**Phase 2** +- Products/services/company pages support +- Schema + metadata output + +**Phase 3** +- Taxonomy archive optimization +- Batch optimization + +**Phase 4** +- Full automation stage integration + +--- + +## 9) Non‑Goals (v1) +- Shopify/custom CMS support +- Automated schema validation tools +- Automatic publishing without review + +--- + +## 10) Success Criteria +- Increased keyword coverage vs cluster targets +- Higher content quality scores (before/after) +- Improved SERP performance for optimized pages + +--- + +## 11) Dependencies +- Cluster data quality in Planner +- WordPress sync reliability +- Unified settings availability + +--- + +## 12) Risks & Mitigations +- **Risk:** Over‑optimization → **Mitigation:** density caps + manual review. +- **Risk:** Wrong cluster mapping → **Mitigation:** suggestion + override flow. +- **Risk:** Schema mismatch → **Mitigation:** type validation + preview. + +--- + +## 13) Future Extensions (Post‑WordPress) +- Shopify product catalogs +- Custom CMS adapters +- Automated schema validation pipeline +- SERP‑based optimization suggestions diff --git a/docs/plans/Future_Moduels_Features/Socializer_Video_Modules_Plan.md b/docs/plans/Future_Moduels_Features/Socializer_Video_Modules_Plan.md new file mode 100644 index 00000000..c4b3a149 --- /dev/null +++ b/docs/plans/Future_Moduels_Features/Socializer_Video_Modules_Plan.md @@ -0,0 +1,187 @@ +# Socializer + Video Content Creator Plan (Detailed) + +**Scope:** Q3–Q4 2026 modules from https://igny8.com/upcoming. Integrations target top social platforms. Content sources are IGNY8‑generated and optimized (new or rewritten), linked back to the original page/post/product/service. + +**Goal:** Automate multi‑platform social publishing and video creation for every IGNY8 content item, using consistent app structure (Ideas → Tasks → Content → Images → Publish + Automation + Calendar). + +--- + +## 1) Socializer Module (Multi‑Platform Social Publishing) + +### 1.1 Core Capabilities +- Auto‑generate platform‑specific social posts from any IGNY8 content item. +- Schedule and auto‑publish to connected social accounts. +- Maintain back‑links to the original page/post/product/service. +- Provide a unified social calendar integrated with content calendar. + +### 1.2 Content Sources (What can be socialized) +- Posts (blog/article) +- Pages (static) +- Products (WooCommerce) +- Services (custom post type) +- Company pages +- Taxonomy landing pages + +**Rule:** Any IGNY8 content item (new or optimized) can generate social content. + +### 1.3 Platform Targets (Phase 1) +- LinkedIn +- Twitter/X +- Facebook +- Instagram (posts + reels) +- TikTok (short video) + +### 1.4 Platform‑Specific Output +- **Text posts:** title + summary + CTA + link +- **Captions:** tone/length variations per platform +- **Images:** resized and cropped per platform specs +- **Short videos / reels:** generated from content (via Video module) + +### 1.5 Social Post Types +- **Announcement:** “New article/product/service” with link +- **Highlights:** key takeaways + CTA +- **Quote cards:** single insight with branded template +- **FAQ snippets:** for services or product categories +- **Carousel (future):** multi‑panel posts + +### 1.6 Scheduling & Automation +- Auto‑publish on content approval or scheduled publish. +- Schedule rules: time windows, frequency caps, platform‑specific limits. +- Sync with Publisher scheduling (same calendar). + +--- + +## 2) Video Content Creator (AI Video Generation & Publishing) + +### 2.1 Core Capabilities +- Convert articles/pages into video scripts. +- Generate short‑form videos (Reels/Shorts/TikTok). +- Generate long‑form YouTube videos with chapters. +- Auto‑publish to video platforms. + +### 2.2 Video Types +- **Short:** 15–60s highlights +- **Medium:** 60–180s summaries +- **Long:** 5–12 min explainer (YouTube) + +### 2.3 Video Outputs +- Script + captions +- AI voiceover or user‑uploaded voice +- Visuals: stock + AI images + brand templates +- Titles, descriptions, tags (SEO optimized) + +### 2.4 Publishing Targets (Phase 1) +- YouTube +- TikTok +- Instagram Reels +- YouTube Shorts + +--- + +## 3) Integration with IGNY8 Content Workflow + +### 3.1 Trigger Points +- On **content approval** +- On **scheduled publish** +- On **optimizer rewrite completion** + +### 3.2 Link‑Back Rule +Every social/video post must link to the original page/post/product on the site. + +### 3.3 Metadata Alignment +- Use IGNY8 meta title + description as base. +- Add platform‑specific variations. + +--- + +## 4) App‑Consistent Architecture + +### 4.1 Backend Modules (Proposed) +- `backend/igny8_core/modules/socializer/` +- `backend/igny8_core/business/social/` +- `backend/igny8_core/modules/video/` +- `backend/igny8_core/business/video/` + +### 4.2 Data Models (Proposed) + +**SocialAccount** +- `account`, `site`, `platform`, `auth_tokens`, `status` + +**SocialPost** +- `content_id`, `platform`, `post_type`, `caption`, `media_url`, `status`, `scheduled_at`, `published_at`, `external_id` + +**VideoProject** +- `content_id`, `type`, `script`, `voice`, `status`, `video_url`, `published_at` + +**EngagementMetric** +- `platform`, `post_id`, `views`, `likes`, `comments`, `shares` + +--- + +## 5) API Endpoints (Proposed) + +### Socializer +- `POST /api/v1/social/accounts/connect/` +- `GET /api/v1/social/accounts/` +- `POST /api/v1/social/posts/generate/` +- `POST /api/v1/social/posts/schedule/` +- `POST /api/v1/social/posts/publish/` +- `GET /api/v1/social/posts/status/` + +### Video Creator +- `POST /api/v1/video/projects/generate/` +- `POST /api/v1/video/projects/publish/` +- `GET /api/v1/video/projects/status/` + +--- + +## 6) Frontend Pages + +### Socializer +- `/social/accounts` – connect platforms +- `/social/calendar` – unified social calendar +- `/social/posts` – list + status + actions + +### Video Creator +- `/video/projects` – list + status +- `/video/preview/:id` – script + preview + publish + +--- + +## 7) Scheduling & Automation Rules +- Respect per‑platform rate limits. +- Enforce daily/weekly caps per site. +- Time‑slot scheduling aligned with Publisher rules. + +--- + +## 8) Rollout Phases + +**Phase 1** +- Social accounts + post generation +- Manual scheduling + publish + +**Phase 2** +- Auto‑publish on content approval +- Calendar integration + +**Phase 3** +- Video creator (short‑form) +- Auto‑publish to video platforms + +**Phase 4** +- Long‑form video creation + analytics + +--- + +## 9) Success Criteria +- Every IGNY8 content item can generate social + video assets. +- Social posts consistently link back to the original page. +- Improved traffic attribution from social channels. + +--- + +## 10) Non‑Goals (v1) +- Social ad automation +- Outreach automation +- Shopify/custom CMS publishing diff --git a/docs/plans/Future_Moduels_Features/Taxonomy_Term_Content_Plan.md b/docs/plans/Future_Moduels_Features/Taxonomy_Term_Content_Plan.md new file mode 100644 index 00000000..6f7acba4 --- /dev/null +++ b/docs/plans/Future_Moduels_Features/Taxonomy_Term_Content_Plan.md @@ -0,0 +1,199 @@ +# Taxonomy & Term Content Plan (Detailed) + +**Scope:** WordPress-only for current release. Shopify/custom sites remain future. + +**Goal:** Make taxonomy terms and archives first‑class content pages (SEO landing pages) that are generated, optimized, and mapped to clusters using the same Planner → Writer → Optimizer pipeline as posts. + +--- + +## 1) Current App Findings (Relevant Parts) + +### 1.1 Content Models Already Support Taxonomy +- `Tasks` supports `content_type='taxonomy'` and `content_structure` values including `category_archive`, `tag_archive`, `attribute_archive`, `cluster_hub`. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py). +- `Content` supports `content_type='taxonomy'` and taxonomy‑specific structures. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py). +- `ContentTaxonomy` exists with `external_taxonomy`, `external_id`, `description`, and `metadata` for sync. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py). + +### 1.2 WordPress Client Already Knows Taxonomies +- WordPress REST: `get_categories`, `get_tags`, `create_category`, `create_tag`. See [backend/igny8_core/utils/wordpress.py](../../backend/igny8_core/utils/wordpress.py). +- WooCommerce: product categories + attributes and terms are fetchable. See [backend/igny8_core/utils/wordpress.py](../../backend/igny8_core/utils/wordpress.py). + +### 1.3 Sync Service Partially Implemented (Then Removed) +- Taxonomy sync functions exist but are currently **skipped** with a “legacy removed” note. See [backend/igny8_core/business/integration/services/content_sync_service.py](../../backend/igny8_core/business/integration/services/content_sync_service.py). +- Posts sync assigns placeholder categories/tags by ID; product sync stores categories/tags/attributes in metadata only. + +**Conclusion:** The database and data model already allow taxonomy content, but sync + content generation for terms is incomplete. + +--- + +## 2) Target Outcome + +### 2.1 First‑Class Term Landing Pages +Every taxonomy term becomes a **rich SEO landing page** rather than a simple list of posts. + +**Examples** +- Category: “Electric Toothbrushes” → full landing page with intro, buyer guidance, top items, FAQs. +- Tag: “Remote Work” → topical overview + curated posts. +- Product Attribute: “Material: Stainless Steel” → attribute landing page. + +### 2.2 Cluster‑Aligned Structure +- Each term is mapped to **primary cluster** + optional secondary clusters. +- Each term page follows a **cluster‑aligned structure** (H2/H3 outline, keyword coverage, semantic variants). + +### 2.3 Same Pipeline as Posts +Planner → Writer → Optimizer should work for taxonomy pages the same way it works for posts. + +--- + +## 3) Functional Scope + +### 3.1 Content Writer for All Terms (Default + Custom Taxonomies) +- WordPress default: category, post_tag +- WooCommerce: product_cat, product_tag +- Product attributes (e.g., `pa_color`, `pa_size`) +- Custom taxonomies (configurable list from site integration) + +### 3.2 Products Pages Writing +- Use existing product sync data + clusters to generate product landing pages and individual product enhancements. + +### 3.3 Services / Company Pages Writing +- Use existing Writer structures (`service_page`, `business_page`, `general`) and cluster mapping. + +### 3.4 Cluster Hub Pages +- Create **cluster landing pages** that aggregate all related terms + posts + products. + +--- + +## 4) Architecture Plan (Aligned with App) + +### 4.1 Taxonomy Sync (WordPress) +**Add/Restore taxonomy sync** in `ContentSyncService`: +- Fetch categories & tags via `WordPressClient`. +- Fetch WooCommerce product categories + attributes + terms. +- Sync to `ContentTaxonomy` with correct `external_taxonomy` values. + +**Why:** term metadata is required for mapping, writing, and linking. + +--- + +### 4.2 Term‑to‑Cluster Mapping +**New service:** `business/optimization/cluster_mapping.py` (shared with Optimizer). +- Map term name/description to clusters. +- Persist mapping in `Content.cluster` and/or a `ContentClusterMap`. + +--- + +### 4.3 Term Content Generation (Writer) +**Flow (mirrors posts):** +1. Create `ContentIdea` from term + cluster data. +2. Create `Tasks` with `content_type='taxonomy'` and appropriate `content_structure`. +3. Use Writer to generate HTML content, meta, and structure. +4. Save as `Content` linked to `ContentTaxonomy`. + +**Suggested structures:** +- Category → `category_archive` +- Tag → `tag_archive` +- Attribute → `attribute_archive` +- Cluster landing → `cluster_hub` + +--- + +### 4.4 Publishing Back to WordPress +**WordPress update targets:** +- Write generated content to **term description** for taxonomy pages. +- Store structured content in term meta (future: ACF or custom IGNY8 plugin fields). + +**Notes:** +- WordPress term descriptions accept HTML and can be displayed by themes. + +--- + +### 4.5 Optimizer Alignment +Use Optimizer to: +- Rewrite existing term descriptions. +- Align term pages with cluster keyword targets. +- Inject schema and metadata updates. + +--- + +## 5) API & UI Plan + +### 5.1 API Endpoints (Proposed) +- `GET /api/v1/taxonomy/terms/?site_id=` +- `POST /api/v1/taxonomy/terms/sync/` +- `POST /api/v1/taxonomy/terms/create_tasks/` +- `POST /api/v1/taxonomy/terms/optimize/` +- `POST /api/v1/taxonomy/terms/publish/` + +### 5.2 UI Pages +- **Taxonomy Overview**: list terms, cluster mapping status, content status. +- **Term Content Editor**: preview + rewrite + publish. +- **Cluster Hub Manager**: cluster landing pages and cross‑links. + +--- + +## 6) Keyword + Cluster Strategy + +### 6.1 Term‑Cluster Assignment +- Auto‑assign cluster based on keyword overlap + semantic similarity. +- Manual override in UI. + +### 6.2 Term Keyword Targets +- Use cluster keywords as primary/secondary targets. +- Add term‑specific modifiers (e.g., “best”, “vs”, “near me”). + +--- + +## 7) Term Landing Page Structure (SEO‑Rich) + +**Default sections (taxonomy pages):** +1. Intro + term definition +2. Key subtopics (H2/H3) +3. Top related posts/products/services +4. FAQs +5. Internal links to related clusters + +**Schema:** +- `CollectionPage` or `WebPage` +- `FAQPage` if FAQs present + +--- + +## 8) Rollout Phases + +**Phase 1** +- Taxonomy sync (categories + tags) +- Term mapping to clusters +- Writer tasks for term pages + +**Phase 2** +- WooCommerce product categories + attributes +- Term optimization with Optimizer + +**Phase 3** +- Cluster hub pages +- Full taxonomy publish flow + +**Phase 4** +- Custom taxonomies configuration +- Cross‑site cluster navigation + +--- + +## 9) Success Criteria +- All taxonomy terms have generated content and cluster mapping. +- Term landing pages outperform plain archive pages. +- Consistent internal linking between clusters, terms, and posts. + +--- + +## 10) Risks & Mitigations +- **Risk:** Themes not showing term descriptions → **Mitigation:** IGNY8 plugin blocks or template guidance. +- **Risk:** Incorrect cluster mapping → **Mitigation:** manual override + suggestions. +- **Risk:** Over‑optimization → **Mitigation:** density caps + manual review. + +--- + +## 11) Non‑Goals (v1) +- Shopify taxonomy sync +- Custom CMS adapters +- Automated publishing without review diff --git a/docs/plans/KEYWORDS-LIBRARY-REDESIGN-PLAN.md b/docs/plans/KEYWORDS-LIBRARY-REDESIGN-PLAN.md deleted file mode 100644 index 0d6ed650..00000000 --- a/docs/plans/KEYWORDS-LIBRARY-REDESIGN-PLAN.md +++ /dev/null @@ -1,855 +0,0 @@ -# Keywords Library Page Redesign Plan - -**Created:** January 18, 2026 -**Updated:** January 19, 2026 _(v1.8.2 released)_ -**Status:** ✅ COMPLETED & DOCUMENTED (v1.8.2) -**Page:** `/keywords-library` (was `/setup/add-keywords`) -**Priority:** 🟢 COMPLETED - ---- - -## Executive Summary - -Comprehensive redesign of the Keywords Library page completed and deployed in **v1.8.2**: -1. ✅ **Standardize naming** to "Keywords Library" across frontend, backend, URLs, menus, and admin -2. ✅ **Implement cascading filters** like Planner pages (Keywords, Clusters, Ideas) -3. ⬜ **Remove sector selector** from AppHeader, use site-only selector (partial - route updated) -4. ✅ **Add Sector Metric Cards** with clickable filtering + 6 bulk add stat options -5. ✅ **Redesign Smart Suggestions** to appear after search/filter with breathing indicator -6. ⬜ **Center filter bar** with sector filter added, matching Planner page styling (needs polish) -7. ⬜ **Show table data by default** (remove "Browse" toggle) (kept existing UX for now) -8. ✅ **No backward compatibility** - single source of truth -9. ✅ **CRITICAL FIX:** Sector-specific filtering - sites now only see keywords from their configured sectors - -**Release:** Version 1.8.2 - January 19, 2026 -**Changelog:** See `/CHANGELOG.md` for complete details -**API Documentation:** See `/docs/20-API/ENDPOINTS.md` for Keywords Library endpoints - ---- - -## Part 1: Terminology Standardization - -### Current State (Inconsistent) - -| Location | Current Term | Usage | -|----------|--------------|-------| -| Sidebar | "Keyword Library" | ❌ Should be "Keywords Library" | -| Page Title | "Keyword Library" | ❌ Should be "Keywords Library" | -| URL | `/setup/add-keywords` | ❌ Legacy | -| Backend Model | `SeedKeyword` | ✅ Keep internal | -| Backend URL | `/v1/auth/seed-keywords/` | ❌ Legacy | -| Backend Admin | "Industry Sector Keywords" | ❌ Should be "Keywords Library" | -| Frontend API | `fetchSeedKeywords()` | ❌ Legacy | -| High Opportunity | "Quick-Start Keywords" | ❌ Different term | -| Search Modal | Mixed terms | ❌ Inconsistent | -| Onboarding | "Add Keywords" | ❌ Legacy | -| Marketing Pages | "Seed Keywords", "High-Opportunity" | ❌ Mixed | - -### Target State (Unified) - -**Standardized Term:** "Keywords Library" (plural "Keywords") -**Internal/Code:** Keep `SeedKeyword` model name internally - -| Location | New Term | -|----------|----------| -| Sidebar | "Keywords Library" | -| Page Title | "Keywords Library" | -| URL | `/keywords-library` (**NO** redirect from legacy) | -| Backend URL | `/v1/keywords-library/` (**NO** legacy alias) | -| Backend Admin | "Keywords Library" | -| Frontend API | `fetchKeywordsLibrary()` (replace `fetchSeedKeywords`) | -| Smart Suggestions | "Smart Suggestions" | -| Search Modal | "Keywords Library" | -| Onboarding Step | "Browse Keywords Library" | - -### Files to Update - -``` -Frontend: -- src/layout/AppSidebar.tsx - Menu label → "Keywords Library" -- src/layout/AppHeader.tsx - Route patterns -- src/App.tsx - Route definition (NO redirect, direct change) -- src/components/common/SearchModal.tsx - Search references -- src/components/onboarding/OnboardingWizard.tsx - Step 4 name -- src/components/onboarding/steps/Step4AddKeywords.tsx - Rename to Step4KeywordsLibrary.tsx -- src/components/sites/SiteSetupChecklist.tsx - Link text -- src/services/api.ts - Rename function to fetchKeywordsLibrary() -- src/marketing/pages/Pricing.tsx - Feature descriptions -- src/marketing/pages/Solutions.tsx - Feature descriptions - -Backend: -- igny8_core/auth/urls.py - Change URL to /keywords-library/ -- igny8_core/admin/ - Change admin menu label to "Keywords Library" -- Keep model name as SeedKeyword (internal only) -``` - ---- - -## Part 2: Filter System Redesign - -### Current Filters (Keywords Library) - -``` -[Search] [Country ▼] [Difficulty ▼] [Status ▼] -``` - -**Issues:** -1. ❌ No "Clear Filters" button near active filter indicator -2. ❌ No Volume filter (exists on Planner Keywords page) -3. ❌ No Sector filter in filter bar -4. ❌ Hardcoded country/difficulty options (not cascading) -5. ❌ Filters don't show only available options based on current data -6. ❌ Active/Clear button positioning doesn't match Planner pages - -### Target Filters (Match Planner Pages Pattern) - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ [🔍 Search] [Sector ▼] [Volume ▼] [Difficulty ▼] [Country ▼] [Status ▼] │ -│ │ -│ Active: 2 filters [Clear] ← Same position as Planner pages │ -│ │ -│ ℹ️ Search 54,180 keywords. Filter by volume or difficulty to find your │ -│ perfect keywords! │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -**Improvements:** -1. ✅ Active count + Clear button positioned **same as Planner pages** -2. ✅ Add Volume range filter (min/max popup like Planner pages) -3. ✅ Add Sector filter dropdown -4. ✅ Keep "Not Yet Added" status filter (in_workflow filter) -5. ✅ Implement cascading filters - options reflect available data -6. ✅ Center filter bar with explainer text below - -### Filter: Status Options - -| Value | Label | Description | -|-------|-------|-------------| -| `all` | All Keywords | Show all keywords | -| `available` | Not Yet Added | Keywords not in any workflow | -| `in_workflow` | In Workflow | Keywords already added to site | - -### Backend API Changes - -**New Endpoint:** `GET /v1/keywords-library/filter_options/` - -Returns available filter options based on current filters (cascading): - -```python -# Example Request -GET /v1/keywords-library/filter_options/?industry=5§or=12&difficulty_max=40 - -# Response -{ - "sectors": [ - {"value": 12, "label": "Technology", "count": 1250}, - {"value": 15, "label": "Mobile Apps", "count": 340}, - ... - ], - "countries": [ - {"value": "US", "label": "United States", "count": 1250}, - {"value": "GB", "label": "United Kingdom", "count": 340}, - ... - ], - "difficulties": [ - {"value": "1", "label": "Very Easy (1-20)", "count": 890}, - {"value": "2", "label": "Easy (21-40)", "count": 450}, - {"value": "3", "label": "Medium (41-60)", "count": 320}, - {"value": "4", "label": "Hard (61-80)", "count": 180}, - {"value": "5", "label": "Very Hard (81-100)", "count": 90}, - ], - "volume_stats": { - "min": 0, - "max": 421000, - "avg": 5420, - "p50": 1200, - "p90": 15000 - }, - "total_matching": 1590 -} -``` - -### Difficulty Mapping (Backend 1-100 → Frontend 1-5) - -| Frontend Level | Label | Backend Range | -|----------------|-------|---------------| -| 1 | Very Easy | 1-20 | -| 2 | Easy | 21-40 | -| 3 | Medium | 41-60 | -| 4 | Hard | 61-80 | -| 5 | Very Hard | 81-100 | - -**Low Difficulty = Level 1 and 2 (backend ≤ 40)** - -### Frontend Changes - -1. **Add `fetchKeywordsLibraryFilterOptions()` API function** -2. **Add Sector filter dropdown** (populated from site's sectors) -3. **Add Volume filter component** (reuse from Keywords.tsx) -4. **Position Active/Clear same as Planner pages** -5. **Load filter options dynamically** based on industry/sector selection -6. **Re-load options when any filter changes** (cascading) - ---- - -## Part 3: App Header Selector Change - -### Current Behavior - -- Keywords Library page shows `SiteAndSectorSelector` (Site + Sector dropdowns) -- This is redundant since page will have sector cards and sector filter - -### Target Behavior - -- Show `SingleSiteSelector` (Site only, like Automation pages) -- Remove from `SITE_AND_SECTOR_ROUTES` array -- Add to `SINGLE_SITE_ROUTES` array - -### Code Change (AppHeader.tsx) - -```diff -const SITE_AND_SECTOR_ROUTES = [ - '/planner', - '/writer', -- '/setup/add-keywords', -]; - -const SINGLE_SITE_ROUTES = [ - '/automation', - '/publisher', - '/account/content-settings', - '/sites', -+ '/keywords-library', -]; -``` - ---- - -## Part 4: Sector Metric Cards - -### Design - -Clickable sector cards that filter the table when clicked. Each card shows stats and has 5-6 bulk add options. - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ Your Site Sectors [Add Sector]│ -│ │ -│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ -│ │ 💻 Technology │ │ 📱 Mobile Apps │ │ 🌐 Web Dev │ │ -│ │ ─────────────────── │ │ ─────────────────── │ │ ─────────────────── │ │ -│ │ │ │ │ │ │ │ -│ │ Total: 1,245 │ │ Total: 892 │ │ Total: 456 │ │ -│ │ Available: 1,200 │ │ Available: 880 │ │ Available: 456 │ │ -│ │ In Workflow: 45 │ │ In Workflow: 12 │ │ In Workflow: 0 │ │ -│ │ │ │ │ │ │ │ -│ │ ─── Quick Add ───── │ │ ─── Quick Add ───── │ │ ─── Quick Add ───── │ │ -│ │ │ │ │ │ │ │ -│ │ 📈 High Volume │ │ 📈 High Volume │ │ 📈 High Volume │ │ -│ │ 125 kw (>8.5K) │ │ 67 kw (>6.2K) │ │ 50 kw (>3.4K) │ │ -│ │ [+50] [+100] │ │ [+50] [+67] │ │ [+50] │ │ -│ │ │ │ │ │ │ │ -│ │ 🎯 Low Difficulty │ │ 🎯 Low Difficulty │ │ 🎯 Low Difficulty │ │ -│ │ 340 kw (≤40) │ │ 212 kw (≤40) │ │ 89 kw (≤40) │ │ -│ │ [+50] [+100] │ │ [+50] [+100] │ │ [+50] [+89] │ │ -│ │ │ │ │ │ │ │ -│ │ 🔥 High Vol + Easy │ │ 🔥 High Vol + Easy │ │ 🔥 High Vol + Easy │ │ -│ │ 45 kw │ │ 28 kw │ │ 12 kw │ │ -│ │ [+45] │ │ [+28] │ │ [+12] │ │ -│ │ │ │ │ │ │ │ -│ │ 💎 Premium (>50K) │ │ 💎 Premium (>50K) │ │ 💎 Premium (>50K) │ │ -│ │ 12 kw │ │ 8 kw │ │ 3 kw │ │ -│ │ [+12] │ │ [+8] │ │ [+3] │ │ -│ │ │ │ │ │ │ │ -│ │ 🌱 Long Tail │ │ 🌱 Long Tail │ │ 🌱 Long Tail │ │ -│ │ 890 kw (4+ words)│ │ 654 kw (4+ words)│ │ 312 kw (4+ words)│ │ -│ │ [+50] [+100] │ │ [+50] [+100] │ │ [+50] [+100] │ │ -│ │ │ │ │ │ │ │ -│ │ [Browse All →] │ │ [Browse All →] │ │ [Browse All →] │ │ -│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │ -│ │ -│ 💡 Click any card to filter the table by that sector │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### Click Behavior - -- **Click on sector card** → Filter table by that sector -- **Click on Quick Add button** → Add keywords matching that criteria - -### Stats Per Sector Card (6 Options) - -Based on actual keyword data analysis (volume ranges 50-281,000, difficulty 0-99). -**Dynamic fallback thresholds** ensure every sector shows useful data: - -| Stat | Criteria | Fallback Logic | Example | -|------|----------|----------------|---------| -| 📈 **High Volume** | Top 50/100 by volume | Dynamic threshold based on available data | "125 kw (>8.5K)" | -| 🎯 **Low Difficulty** | Difficulty ≤ 40 (levels 1-2) | Fixed threshold | "340 kw (≤40)" | -| 🔥 **Best Opportunities** | High vol + Difficulty ≤ 40 | Combines above two criteria | "45 kw" | -| 💎 **Premium Traffic** | Volume > 50,000 | If 0 → try >25,000 → if 0 → try >10,000 | "12 kw (>50K)" | -| 🌱 **Long Tail** | Words ≥ 4 AND Volume > 1,000 | If 0 → try >500 → if 0 → try >200 | "890 kw (4+ words, >1K)" | -| ⚡ **Quick Wins** | Difficulty ≤ 20 AND Volume > 1,000 + Available | If 0 → try >500 → if 0 → try >200 | "67 kw" | - -### Dynamic Threshold Fallback Logic - -```python -# Premium Traffic - cascading volume thresholds -def get_premium_traffic(keywords): - for threshold in [50000, 25000, 10000]: - count = keywords.filter(volume__gt=threshold).count() - if count > 0: - return {"count": count, "threshold": threshold} - return {"count": 0, "threshold": 10000} - -# Long Tail - cascading volume with word count -def get_long_tail(keywords): - base = keywords.filter(word_count__gte=4) - for threshold in [1000, 500, 200]: - count = base.filter(volume__gt=threshold).count() - if count > 0: - return {"count": count, "min_volume": threshold} - return {"count": 0, "min_volume": 200} - -# Quick Wins - cascading volume with low difficulty + available -def get_quick_wins(keywords, attached_ids): - base = keywords.filter(difficulty__lte=20).exclude(id__in=attached_ids) - for threshold in [1000, 500, 200]: - count = base.filter(volume__gt=threshold).count() - if count > 0: - return {"count": count, "min_volume": threshold} - return {"count": 0, "min_volume": 200} -``` - -This ensures **every sector shows meaningful data** regardless of size, making the feature always useful and operational. - -### High Volume Dynamic Threshold - -Instead of fixed 10,000 threshold: -- Get top 50 keywords by volume for sector -- Show threshold as ">X" where X = lowest volume in top 50 -- If < 50 keywords available, use top 100 threshold -- Example: "125 kw (>8,540)" means 125 keywords with volume > 8,540 - -### Bulk Add Options - -Each stat shows add buttons based on availability: -- `[+50]` - Add top 50 -- `[+100]` - Add top 100 (if > 50 available) -- `[+200]` - Add top 200 (if > 100 available) -- `[+N]` - Add all N (if N ≤ 200) - -**Always show confirmation modal before adding.** - -### Backend API - -**Endpoint:** `GET /v1/keywords-library/sector_stats/` - -```python -# Request -GET /v1/keywords-library/sector_stats/?site_id=21 - -# Response -{ - "sectors": [ - { - "sector_id": 12, - "sector_name": "Technology", - "sector_slug": "technology", - "total_keywords": 1245, - "available": 1200, - "in_workflow": 45, - "stats": { - "high_volume": { - "count": 125, - "threshold": 8540, // Dynamic: lowest volume in top 50/100 - "total_volume": 1200000 - }, - "low_difficulty": { - "count": 340, - "threshold": 40, // Backend value (maps to frontend level 2) - "total_volume": 450000 - }, - "high_vol_easy": { - "count": 45, - "description": "High volume + Low difficulty" - }, - "premium": { - "count": 12, - "threshold": 50000, // Dynamic: 50K → 25K → 10K fallback - "used_fallback": false - }, - "long_tail": { - "count": 890, - "min_words": 4, - "min_volume": 1000, // Dynamic: 1K → 500 → 200 fallback - "used_fallback": false - }, - "quick_wins": { - "count": 67, - "difficulty_max": 20, // Level 1 only - "min_volume": 1000, // Dynamic: 1K → 500 → 200 fallback - "used_fallback": false - } - } - }, - // ... more sectors - ] -} -``` - -### Styling - -Use **subtle accents** matching IGNY8 design style: -- Light/dark mode compatible -- Muted colors from dashboard/billing/usage pages -- No bright/colorful backgrounds -- Subtle borders and shadows -- Consistent with existing card components - ---- - -## Part 5: Smart Suggestions Section - -### Concept - -Show **Smart Suggestions** dynamically based on current filters/search. Display a **breathing circle indicator** until user interacts with filters or search. - -### Initial State (Before Search/Filter) - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ 💡 Smart Suggestions │ -│ │ -│ ○ Ready-to-use keywords waiting for you! Search for a keyword or apply │ -│ any filter to see smart suggestions... │ -│ ↑ │ -│ Breathing/pulsing circle indicator (subtle animation) │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### After Search/Filter Applied - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ 💡 Smart Suggestions for "seo tools" │ -│ │ -│ ┌────────────────────────────────────┐ ┌───────────────────────────────────┐ │ -│ │ 📈 High Volume Keywords │ │ 🎯 Easy Wins │ │ -│ │ │ │ │ │ -│ │ 89 keywords with >4,200 volume │ │ 156 keywords (difficulty ≤ 40) │ │ -│ │ Combined: 2.4M searches/month │ │ Combined: 890K searches/month │ │ -│ │ │ │ │ │ -│ │ Top 5: seo tools, seo audit, ... │ │ Top 5: local seo, seo tips, ... │ │ -│ │ │ │ │ │ -│ │ [+50] [+100] [+All 89] │ │ [+50] [+100] [+All 156] │ │ -│ └────────────────────────────────────┘ └───────────────────────────────────┘ │ -│ │ -│ ┌────────────────────────────────────┐ ┌───────────────────────────────────┐ │ -│ │ 🔥 Best Opportunities │ │ 🌱 Long Tail Keywords │ │ -│ │ │ │ │ │ -│ │ 45 kw (high volume + easy) │ │ 234 keywords (3+ words) │ │ -│ │ Combined: 1.2M searches/month │ │ Lower competition phrases │ │ -│ │ │ │ │ │ -│ │ [+45] │ │ [+50] [+100] [+200] │ │ -│ └────────────────────────────────────┘ └───────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────┐ │ -│ │ 🔍 All matching "seo tools" - 234 keywords │ │ -│ │ │ │ -│ │ [+50 by Volume] [+50 by Difficulty] [+100] [+200] [+All 234] │ │ -│ └──────────────────────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### Breathing Circle Indicator - -CSS animation for pulsing circle: -```css -.breathing-indicator { - width: 12px; - height: 12px; - border-radius: 50%; - background: var(--muted-foreground); - animation: breathe 2s ease-in-out infinite; -} - -@keyframes breathe { - 0%, 100% { opacity: 0.3; transform: scale(0.9); } - 50% { opacity: 0.8; transform: scale(1.1); } -} -``` - -### Suggestion Categories - -| Category | Criteria | Fallback Logic | -|----------|----------|----------------| -| 📈 High Volume | Top 50/100 by volume | Dynamic threshold | -| 🎯 Easy Wins | Difficulty ≤ 40 | Fixed threshold | -| 🔥 Best Opportunities | High vol + Easy | Combines criteria | -| 💎 Premium | Volume > 50K | 50K → 25K → 10K fallback | -| 🌱 Long Tail | Words ≥ 4 + Vol > 1K | Vol: 1K → 500 → 200 fallback | -| ⚡ Quick Wins | Diff ≤ 20 + Vol > 1K + Available | Vol: 1K → 500 → 200 fallback | - -### Bulk Add Buttons - -| Button | Action | -|--------|--------| -| `[+50]` | Add top 50 sorted by relevant criteria | -| `[+100]` | Add top 100 | -| `[+200]` | Add top 200 | -| `[+All N]` | Add all N matching (shown when N ≤ 200) | -| `[+50 by Volume]` | Add top 50 sorted by volume DESC | -| `[+50 by Difficulty]` | Add top 50 sorted by difficulty ASC | - -**Always show confirmation modal before any bulk add.** - -### Styling - -Match IGNY8 dashboard/billing/usage styling: -- Subtle card backgrounds (muted) -- Light borders -- Dark mode compatible colors -- No bright/colorful accents -- Consistent typography - ---- - -## Part 6: Page Layout Redesign - -### Current Layout - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ [Header with Site+Sector selector] │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ Quick-Start Keywords Section (always shown first) │ -│ │ -│ [Browse All Keywords] button │ -│ │ -│ Table (only shown after clicking Browse) │ -│ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### New Layout - -``` -┌─────────────────────────────────────────────────────────────────────────────────┐ -│ [Header with Site-only selector] │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────────────┐│ -│ │ Sector Metric Cards (clickable - filters table by sector) ││ -│ │ - 5-6 bulk add stat options per card ││ -│ │ - [+50] [+100] [+200] buttons ││ -│ └─────────────────────────────────────────────────────────────────────────────┘│ -│ │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌────────────────────────────────────────────────────────────────────┐ │ -│ │ [🔍 Search] [Sector ▼] [Volume ▼] [Difficulty ▼] [Country ▼] │ │ -│ │ │ │ -│ │ Active: 2 filters [Clear] │ │ -│ └────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ℹ️ Search 54,180 keywords. Filter by volume or difficulty │ -│ to find your perfect keywords! │ -│ │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────────────┐│ -│ │ 💡 Smart Suggestions ││ -│ │ ││ -│ │ ○ Search or filter keywords to see personalized suggestions... ││ -│ │ ↑ breathing indicator ││ -│ │ ││ -│ │ (After search/filter: shows suggestion cards with [+50] [+100] buttons) ││ -│ └─────────────────────────────────────────────────────────────────────────────┘│ -│ │ -├─────────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ Keywords Table (always shown, data loaded by default) │ -│ - Shows first 500 records (with server-side sorting/filtering) │ -│ - Pagination shows total count │ -│ - Sorted by volume DESC by default │ -│ │ -└─────────────────────────────────────────────────────────────────────────────────┘ -``` - -### Key Layout Changes - -1. **Site-only selector** in header (no sector dropdown) -2. **Sector cards at top** - clickable to filter table -3. **Centered filter bar** with sector filter + active/clear like Planner -4. **Smart Suggestions** - breathing indicator until search/filter -5. **Table always visible** - no "Browse" toggle -6. **Confirmation modal** for all bulk adds - ---- - -## Part 7: Implementation Tasks - -### Phase 1: Backend API Updates - -| Task | File | Priority | -|------|------|----------| -| Add `/filter_options/` endpoint | `auth/views.py` | High | -| Add `/sector_stats/` endpoint with 6 stat types | `auth/views.py` | High | -| Change URL to `/keywords-library/` (no alias) | `auth/urls.py` | High | -| Update admin menu to "Keywords Library" | `admin/` | High | -| Support volume_min/max filters | `auth/views.py` | High | -| Support sector filter | `auth/views.py` | High | -| Implement cascading filter logic | `auth/views.py` | High | -| Add bulk add endpoint with confirmation | `auth/views.py` | High | - -### Phase 2: Frontend Filter System - -| Task | File | Priority | -|------|------|----------| -| Rename `fetchSeedKeywords` → `fetchKeywordsLibrary` | `services/api.ts` | High | -| Add `fetchKeywordsLibraryFilterOptions()` | `services/api.ts` | High | -| Add `fetchKeywordsLibrarySectorStats()` | `services/api.ts` | High | -| Add Sector filter dropdown | `KeywordsLibrary.tsx` | High | -| Add Volume filter component | `KeywordsLibrary.tsx` | High | -| Position Active/Clear same as Planner | `KeywordsLibrary.tsx` | High | -| Implement cascading filter loading | `KeywordsLibrary.tsx` | High | -| Center filter bar + add explainer | `KeywordsLibrary.tsx` | Medium | - -### Phase 3: Selector & Layout Changes - -| Task | File | Priority | -|------|------|----------| -| Move route to `SINGLE_SITE_ROUTES` | `AppHeader.tsx` | High | -| Change route to `/keywords-library` | `App.tsx` | High | -| Remove "Browse" toggle, show table by default | `KeywordsLibrary.tsx` | High | -| Remove High Opportunity section | `KeywordsLibrary.tsx` | Medium | - -### Phase 4: Sector Metric Cards - -| Task | File | Priority | -|------|------|----------| -| Create SectorMetricCard component | `components/keywords-library/` | High | -| Implement 6 stat types per card | `SectorMetricCard.tsx` | High | -| Add click-to-filter behavior | `KeywordsLibrary.tsx` | High | -| Add [+50] [+100] [+200] buttons | `SectorMetricCard.tsx` | High | -| Add confirmation modal for bulk add | `KeywordsLibrary.tsx` | High | - -### Phase 5: Smart Suggestions - -| Task | File | Priority | -|------|------|----------| -| Create SmartSuggestions component | `components/keywords-library/` | High | -| Add breathing circle indicator | `SmartSuggestions.tsx` | High | -| Show suggestions after search/filter | `KeywordsLibrary.tsx` | High | -| Add bulk add buttons [+50] [+100] [+200] | `SmartSuggestions.tsx` | High | -| Implement 6 suggestion categories | `SmartSuggestions.tsx` | Medium | - -### Phase 6: Naming Standardization - -| Task | File | Priority | -|------|------|----------| -| Update sidebar label → "Keywords Library" | `AppSidebar.tsx` | High | -| Update SearchModal references | `SearchModal.tsx` | Medium | -| Rename Step4AddKeywords → Step4KeywordsLibrary | `onboarding/steps/` | Medium | -| Update marketing pages | `Pricing.tsx`, `Solutions.tsx` | Low | - -### Phase 7: Confirmation Modal - -| Task | File | Priority | -|------|------|----------| -| Create BulkAddConfirmation modal | `components/keywords-library/` | High | -| Show count and criteria being added | `BulkAddConfirmation.tsx` | High | -| Always require confirmation for bulk add | `KeywordsLibrary.tsx` | High | - ---- - -## Part 8: No Backward Compatibility - -### Single Source of Truth - -**No legacy URLs, no aliases, no fallbacks.** - -| Item | Action | -|------|--------| -| `/setup/add-keywords` URL | **REMOVE** - change to `/keywords-library` | -| `/v1/auth/seed-keywords/` API | **REMOVE** - change to `/v1/keywords-library/` | -| `fetchSeedKeywords()` function | **RENAME** to `fetchKeywordsLibrary()` | -| Backend admin "Industry Sector Keywords" | **RENAME** to "Keywords Library" | -| All references to old terms | **UPDATE** to new terms | - -### Route Change (App.tsx) - -```tsx -// BEFORE -} /> - -// AFTER (no redirect, direct change) -} /> -``` - -### API Change (auth/urls.py) - -```python -# BEFORE -path('seed-keywords/', SeedKeywordViewSet.as_view({'get': 'list'}), name='seed-keyword-list'), - -# AFTER (no alias) -urlpatterns = [ - path('keywords-library/', include([ - path('', SeedKeywordViewSet.as_view({'get': 'list'}), name='keywords-library-list'), - path('filter_options/', SeedKeywordViewSet.as_view({'get': 'filter_options'}), name='keywords-library-filter-options'), - path('sector_stats/', SeedKeywordViewSet.as_view({'get': 'sector_stats'}), name='keywords-library-sector-stats'), - path('bulk_add/', SeedKeywordViewSet.as_view({'post': 'bulk_add'}), name='keywords-library-bulk-add'), - ])), -] -``` - -### File Renames - -| From | To | -|------|-----| -| `IndustriesSectorsKeywords.tsx` | `KeywordsLibrary.tsx` | -| `Step4AddKeywords.tsx` | `Step4KeywordsLibrary.tsx` | - ---- - -## Part 9: Success Metrics - -| Metric | Current | Target | -|--------|---------|--------| -| Filter usage rate | Low (no volume/sector filter) | High (all filters used) | -| Keywords added per session | ~50 (quick-start only) | 100+ (smart bulk adds) | -| Bulk add usage | N/A | Track [+50], [+100], [+200] clicks | -| Sector card clicks | N/A | Track filtering by sector | -| Smart suggestions engagement | N/A | Track after search/filter | -| Time to first keyword add | Unknown | < 30 seconds | - ---- - -## Part 10: Design Decisions Summary - -| Decision | Choice | Rationale | -|----------|--------|-----------| -| **URL** | `/keywords-library` | Clean, no legacy compat | -| **Naming** | "Keywords Library" (plural) | Consistent across all surfaces | -| **Backward Compat** | None | Single source of truth | -| **Sector cards click** | Filters table | Intuitive UX | -| **High Volume threshold** | Dynamic (top 50/100 lowest) | Adapts to actual data | -| **Low Difficulty** | ≤ 40 (levels 1-2 mapped) | "Easy" keywords | -| **Bulk add options** | 50, 100, 200, All | Flexible choices | -| **Confirmation modal** | Always | Prevent accidental adds | -| **Smart suggestions** | Breathing indicator until search | Encourages interaction | -| **Filter styling** | Match Planner pages | Consistency | - ---- - -## Files Summary - -### Files to Modify - -| File | Changes | -|------|---------| -| `frontend/src/pages/Setup/IndustriesSectorsKeywords.tsx` | Major rewrite → rename to KeywordsLibrary.tsx | -| `frontend/src/services/api.ts` | Rename + add new API functions | -| `frontend/src/layout/AppHeader.tsx` | Move route category | -| `frontend/src/layout/AppSidebar.tsx` | Update label to "Keywords Library" | -| `frontend/src/App.tsx` | Change route (no redirect) | -| `frontend/src/components/common/SearchModal.tsx` | Update references | -| `backend/igny8_core/auth/views.py` | Add new endpoints, update existing | -| `backend/igny8_core/auth/urls.py` | Change URL (no alias) | -| `backend/igny8_core/admin/` | Update menu label | - -### Files to Create - -| File | Purpose | -|------|---------| -| `frontend/src/components/keywords-library/SectorMetricCard.tsx` | Sector stats card with 6 stat options | -| `frontend/src/components/keywords-library/SmartSuggestions.tsx` | Smart suggestions with breathing indicator | -| `frontend/src/components/keywords-library/BulkAddConfirmation.tsx` | Confirmation modal for bulk adds | - -### Files to Rename - -| From | To | -|------|-----| -| `IndustriesSectorsKeywords.tsx` | `KeywordsLibrary.tsx` | -| `Step4AddKeywords.tsx` | `Step4KeywordsLibrary.tsx` | - ---- - -## Approval Checklist - -- [x] Review by Product Owner - **APPROVED** -- [x] Design decisions finalized -- [x] Backend API design approved -- [x] Frontend component design approved -- [x] No backward compatibility confirmed -- [ ] Implementation started - ---- - -## Appendix A: Complete List of Files to Refactor - -### Frontend Source Files (Must Change) - -| File | Changes Required | -|------|------------------| -| `frontend/src/App.tsx` | Change route `/setup/add-keywords` → `/keywords-library`, remove `IndustriesSectorsKeywords` import | -| `frontend/src/layout/AppHeader.tsx` | Remove `/setup/add-keywords` from `SITE_AND_SECTOR_ROUTES`, add `/keywords-library` to `SINGLE_SITE_ROUTES` | -| `frontend/src/layout/AppSidebar.tsx` | Change label "Keyword Library" → "Keywords Library", path `/setup/add-keywords` → `/keywords-library` | -| `frontend/src/services/api.ts` | Rename `fetchSeedKeywords()` → `fetchKeywordsLibrary()`, rename `SeedKeyword` interface (user-facing), update API URL | -| `frontend/src/components/common/SearchModal.tsx` | Change all `/setup/add-keywords` → `/keywords-library`, "Keyword Library" → "Keywords Library" | -| `frontend/src/components/sites/SiteSetupChecklist.tsx` | Change href `/setup/add-keywords` → `/keywords-library` | -| `frontend/src/components/dashboard/QuickActionsWidget.tsx` | Change "Keyword Library" → "Keywords Library" | -| `frontend/src/components/onboarding/steps/Step4AddKeywords.tsx` | **RENAME FILE** → `Step4KeywordsLibrary.tsx`, update imports | -| `frontend/src/components/onboarding/WorkflowGuide.tsx` | Update comment reference to `IndustriesSectorsKeywords` | -| `frontend/src/pages/Setup/IndustriesSectorsKeywords.tsx` | **RENAME FILE** → `KeywordsLibrary.tsx`, **MAJOR REWRITE** | -| `frontend/src/pages/Reference/SeedKeywords.tsx` | Update if needed for consistency | - -### Backend Files (Must Change) - -| File | Changes Required | -|------|------------------| -| `backend/igny8_core/auth/urls.py` | Change route `seed-keywords/` → `keywords-library/` | -| `backend/igny8_core/auth/views.py` | Keep `SeedKeywordViewSet` class name (internal), add new endpoints | -| `backend/igny8_core/auth/serializers.py` | Keep `SeedKeywordSerializer` name (internal) | -| `backend/igny8_core/auth/admin.py` | Update admin label to "Keywords Library" | -| `backend/igny8_core/settings.py` | Change sidebar menu "Seed Keywords" → "Keywords Library" | -| `backend/igny8_core/urls.py` | Update `seedkeyword_csv_template` and `seedkeyword_csv_import` URL paths | - -### Backend Files (Keep Internal - SeedKeyword Model) - -| File | Status | -|------|--------| -| `backend/igny8_core/auth/models.py` | **KEEP** `SeedKeyword` class name (internal) | -| `backend/igny8_core/business/planning/models.py` | **KEEP** `seed_keyword` field reference (internal) | -| `backend/scripts/import_seed_keywords_single.py` | **KEEP** internal script name | -| `backend/scripts/import_all_seed_keywords.py` | **KEEP** internal script name | - -### Documentation Files (Must Update) - -| File | Changes Required | -|------|------------------| -| `docs/INDEX.md` | Update route `/setup/add-keywords` → `/keywords-library` | -| `docs/20-API/ENDPOINTS.md` | Update endpoint `/seed-keywords/` → `/keywords-library/` | -| `docs/90-REFERENCE/SEED-KEYWORDS-IMPORT-GUIDE.md` | Update user-facing terminology, keep internal references | -| `docs/90-REFERENCE/MODELS.md` | Keep `SeedKeyword` model reference (internal) | -| `docs/plans/NAVIGATION_REFACOTR/NAVIGATION_FINAL_COMPLETION_SUMMARY.md` | Update "Keyword Library" → "Keywords Library" | -| `docs/plans/NAVIGATION_REFACOTR/NAVIGATION_REFACTOR_PLAN.md` | Update "Keyword Library" → "Keywords Library" | - -### Other Files (May Need Review) - -| File | Notes | -|------|-------| -| `CHANGELOG.md` | Historical references - may keep as-is | -| `.rules` | Keep `SeedKeyword` (internal model reference) | -| `frontend/dist/` | **REBUILD** after changes | -| `frontend/audit-results/` | Re-run audits after changes | - ---- - -**Status:** READY FOR IMPLEMENTATION - -**Next Steps:** Begin Phase 1 - Backend API Updates diff --git a/docs/plans/LAUNCH-VERIFICATION-CHECKLIST.md b/docs/plans/LAUNCH-VERIFICATION-CHECKLIST.md deleted file mode 100644 index 9a535233..00000000 --- a/docs/plans/LAUNCH-VERIFICATION-CHECKLIST.md +++ /dev/null @@ -1,265 +0,0 @@ -# IGNY8 v1.8.1 Launch Verification Checklist - -**Version:** 1.8.1 -**Created:** January 17, 2026 -**Updated:** January 18, 2026 -**Purpose:** Final end-to-end verification before production launch - ---- - -## Quick Status - -| Section | Items | Status | -|---------|-------|--------| -| 1. User Journey | 12 | ⏳ | -| 2. Content Paths | 8 | ⏳ | -| 3. Settings Verification | 10 | ⏳ | -| 4. Analytics & Billing | 7 | ⏳ | -| 5. Documentation | 6 | ⏳ | -| 6. Design Standards | 5 | ⏳ | -| 7. Future Update Rules | 4 | ⏳ | - ---- - -# 1. USER JOURNEY VERIFICATION - -## 1.1 - Registration & Onboarding - -| # | Test | Expected | Pass | -|---|------|----------|------| -| 1 | Visit `/register` | Form renders, validation works | [ ] | -| 2 | Submit registration | Account created, redirects to wizard | [ ] | -| 3 | Onboarding wizard Step 1 | Welcome screen, "Get Started" works | [ ] | -| 4 | Onboarding wizard Step 2 | Add site with industry/sectors | [ ] | -| 5 | Onboarding wizard Step 3 | WordPress integration (can skip) | [ ] | -| 6 | Onboarding wizard Step 4 | Add initial keywords (can skip) | [ ] | -| 7 | Onboarding wizard Step 5 | Completion summary, go to dashboard | [ ] | - -## 1.2 - Authentication Flows - -| # | Test | Expected | Pass | -|---|------|----------|------| -| 8 | Login with email/password | JWT issued, redirects to dashboard | [ ] | -| 9 | Forgot password flow | Reset email sent, link works | [ ] | -| 10 | Change password (in-app) | Password updated, session valid | [ ] | -| 11 | Logout | Session cleared, redirect to login | [ ] | -| 12 | Token refresh | Automatic refresh before expiry | [ ] | - ---- - -# 2. CONTENT PIPELINE PATHS - -## 2.1 - Manual Pipeline (Full Path) - -| Stage | Action | Verify | Pass | -|-------|--------|--------|------| -| 1 | Add keywords manually | Keywords appear in list, status: pending | [ ] | -| 2 | Run clustering | Clusters created, keywords linked | [ ] | -| 3 | Generate ideas from cluster | Ideas created with title/brief | [ ] | -| 4 | Convert ideas to tasks | Tasks appear in Writer Queue | [ ] | -| 5 | Generate content | Full article with HTML + meta | [ ] | -| 6 | Generate image | Featured image attached to content | [ ] | -| 7 | Review content | Editor works, preview renders | [ ] | -| 8 | Publish to WordPress | Content appears on WP site | [ ] | - -## 2.2 - Automated Pipeline - -| # | Test | Expected | Pass | -|---|------|----------|------| -| 1 | Configure automation (Site Settings > Automation) | Settings save, schedule displays | [ ] | -| 2 | Run automation manually (Run Now) | All enabled stages execute in order | [ ] | -| 3 | Pause automation mid-run | Run pauses after current item | [ ] | -| 4 | Resume paused automation | Continues from saved stage | [ ] | -| 5 | Skip stage configuration | Skipped stages show 0 processed | [ ] | -| 6 | Per-run limits respected | Stages stop at configured limit | [ ] | - -## 2.3 - Publishing Paths - -| # | Test | Expected | Pass | -|---|------|----------|------| -| 1 | Manual publish (single) | Content published immediately | [ ] | -| 2 | Schedule for future | Content scheduled, shows in calendar | [ ] | -| 3 | Bulk schedule | Multiple items scheduled with stagger | [ ] | -| 4 | Auto-approval flow | Review → Approved automatically | [ ] | -| 5 | Auto-publish flow | Scheduled → Published at time | [ ] | -| 6 | Unschedule content | Content removed from schedule | [ ] | - ---- - -# 3. SETTINGS VERIFICATION - -## 3.1 - Site Settings Tabs - -| Tab | Settings to Verify | Pass | -|-----|-------------------|------| -| **General** | Site name, URL, industry, sectors, description | [ ] | -| **Automation** | Schedule, stages, batch sizes, per-run limits | [ ] | -| **Integrations** | WordPress connection status, sync settings | [ ] | - -## 3.2 - Automation Settings (Unified) - -| Setting | Verify | Pass | -|---------|--------|------| -| Enable/disable toggle | Saves and reflects in next run | [ ] | -| Frequency (hourly/daily/weekly) | Next run calculates correctly | [ ] | -| Scheduled days | Only selected days show in schedule | [ ] | -| Time slots | Run starts within selected window | [ ] | -| Stage enable/disable | Disabled stages skipped | [ ] | -| Batch sizes | Correct items per batch | [ ] | -| Per-run limits | Stage stops at limit | [ ] | -| Testing model selection | Uses correct model (is_testing) | [ ] | - -## 3.3 - Account Settings - -| Setting | Page | Verify | Pass | -|---------|------|--------|------| -| Organization name | Account tab | Saves and displays | [ ] | -| Profile info | Profile tab | Name, timezone save | [ ] | -| Password change | Profile tab | Requires old password | [ ] | -| Team members | Team tab | Can invite, list shows | [ ] | - ---- - -# 4. ANALYTICS & BILLING - -## 4.1 - Credits System - -| Test | Expected | Pass | -|------|----------|------| -| Header displays balance | Shows full number (12,000 not 12k) | [ ] | -| Clustering consumes credits | Balance decreases correctly | [ ] | -| Idea generation consumes credits | Balance decreases correctly | [ ] | -| Content generation consumes credits | Token-based calculation correct | [ ] | -| Image generation by tier | Basic=5, Quality=15, Premium=25 | [ ] | -| Zero credits blocks AI | Shows "insufficient credits" error | [ ] | -| Transaction logged | Appears in credit history | [ ] | - -## 4.2 - Billing & Payments - -| Test | Expected | Pass | -|------|----------|------| -| Current plan displays | Shows correct plan name + price | [ ] | -| Upgrade flow works | Stripe/PayPal checkout opens | [ ] | -| Payment history shows | Past invoices listed | [ ] | -| Subscription renewal date | Calculated correctly | [ ] | -| Credits reset date | Matches billing cycle | [ ] | - ---- - -# 5. DOCUMENTATION CHECK - -## 5.1 - Core Documentation - -| Document | Status | Verified | -|----------|--------|----------| -| `docs/INDEX.md` - v1.8.0 | Updated | [ ] | -| `CHANGELOG.md` - v1.8.0 | Updated | [ ] | -| `10-MODULES/AUTOMATION.md` | Reflects unified settings | [ ] | -| `10-MODULES/PUBLISHER.md` | Reflects unified settings | [ ] | -| `20-API/ENDPOINTS.md` | unified-settings endpoint added | [ ] | -| `30-FRONTEND/PAGES.md` | Removed pages documented | [ ] | - -## 5.2 - Help Content - -| Help Section | Accurate | Pass | -|--------------|----------|------| -| Getting Started | Matches current wizard flow | [ ] | -| Pipeline flow | 7-stage + publish accurate | [ ] | -| Settings descriptions | Matches current UI | [ ] | -| FAQ answers | Still accurate | [ ] | - ---- - -# 6. DESIGN STANDARDS COMPLIANCE - -## 6.1 - UI Consistency Check - -| Area | Standard | Verified | -|------|----------|----------| -| Module colors | Planner=green, Writer=yellow, Automation=blue, Publisher=purple | [ ] | -| Buttons | Using `