# 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