igny8/docs/plans/Future_Moduels_Features/Linker_Module_Plan.md

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.

---

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