salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Future Modules planning docs

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2026-01-27 01:12:10 +00:00
parent 75deda304e
commit 2996c86893
13 changed files with 1756 additions and 2560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/plans/4th-jan-refactor/final-model-schemas.md → docs/90-REFERENCE/final-model-schemas.md
View File

168
docs/FILTER_GUIDELINES.md
View File

@@ -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
<TablePageTemplate
filters={pageConfig.filters}
filterValues={{
search: searchTerm,
content_type: contentTypeFilter,
}}
onFilterChange={(key, value) => { /* ... */ }}
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
<TablePageTemplate
onFilterChange={...}
// Missing: onFilterReset
/>
```
## 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

156
docs/plans/Future_Moduels_Features/Content_Types_Writing_Plan.md Normal file
View File

@@ -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

210
docs/plans/Future_Moduels_Features/FB_LinkedIn_Auth_flow_Steps.md Normal file
View File

@@ -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.

0
docs/plans/Future_Moduels_Features/GSC_plnning_to_be_updated_consistent_with_supported_API_and_Igny8_app.md Normal file
View File

264
docs/plans/Future_Moduels_Features/Linker_Module_Plan.md Normal file
View File

@@ -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

235
docs/plans/Future_Moduels_Features/Optimizer_Module_Plan.md Normal file
View File

@@ -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

187
docs/plans/Future_Moduels_Features/Socializer_Video_Modules_Plan.md Normal file
View File

@@ -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

199
docs/plans/Future_Moduels_Features/Taxonomy_Term_Content_Plan.md Normal file
View File

@@ -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

855
docs/plans/KEYWORDS-LIBRARY-REDESIGN-PLAN.md
View File

@@ -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&sector=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
<Route path="/setup/add-keywords" element={<IndustriesSectorsKeywords />} />
// AFTER (no redirect, direct change)
<Route path="/keywords-library" element={<KeywordsLibrary />} />
```
### 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

265
docs/plans/LAUNCH-VERIFICATION-CHECKLIST.md
View File

@@ -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 `<Button>` component everywhere | [ ] |
| Forms | Using `<InputField>`, `<SelectDropdown>` | [ ] |
| Cards | Using `<Card>` with consistent padding | [ ] |
| Loading states | Global loader, no per-page spinners | [ ] |
## 6.2 - Layout Standards
| Rule | Verified |
|------|----------|
| Global padding from AppLayout only (no page-level padding) | [ ] |
| Consistent header height and spacing | [ ] |
| Sidebar navigation states (active, hover) correct | [ ] |
| Responsive breakpoints working (mobile, tablet, desktop) | [ ] |
---
# 7. FUTURE UPDATE RULES
## 7.1 - Version Numbering
```
MAJOR.MINOR.PATCH
MAJOR (X.0.0): Breaking changes, major features
MINOR (x.X.0): New features, significant improvements
PATCH (x.x.X): Bug fixes, minor improvements
```
## 7.2 - Update Checklist (For Every Release)
```
[ ] Update CHANGELOG.md with version entry
[ ] Update docs/INDEX.md version number
[ ] Update relevant module docs if changed
[ ] Update API docs if endpoints changed
[ ] Run ESLint and fix violations
[ ] Run TypeScript strict check
[ ] Test affected user flows manually
```
## 7.3 - Code Standards (Enforce)
| Rule | Enforcement |
|------|-------------|
| Use design system components | ESLint rule |
| No inline styles (use Tailwind) | ESLint rule |
| TypeScript strict mode | tsconfig |
| No console.log in production | ESLint rule |
| API responses typed | TypeScript |
## 7.4 - Documentation Rules
| Document | Update When |
|----------|-------------|
| CHANGELOG.md | Every release |
| Module docs | Module changes |
| API ENDPOINTS.md | Endpoint added/changed/removed |
| PAGES.md | Route added/changed/removed |
| Help content | User-facing feature changes |
---
# SIGN-OFF
## Pre-Launch Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Developer | | | |
| QA | | | |
| Owner | | | |
## Notes
```
Use this space for any issues found during verification:
```
---
**Document Owner:** IGNY8 Team
**Next Review:** After each major version release

1272
docs/plans/SETTINGS-CONSOLIDATION-PLAN.md
View File

File diff suppressed because it is too large Load Diff