Future Modules planning docs
This commit is contained in:
IGNY8 VPS (Salman)
264
docs/plans/Future_Moduels_Features/Linker_Module_Plan.md
Normal file
264
docs/plans/Future_Moduels_Features/Linker_Module_Plan.md
Normal 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
|
||||
Reference in New Issue
Block a user