1279 lines
56 KiB
Markdown
1279 lines
56 KiB
Markdown
# SAG Implementation for IGNY8 — Foundational Architecture Document
|
||
|
||
**Version:** 2.0
|
||
**Status:** Definitive Implementation Reference
|
||
**Scope:** Three-layer SAG architecture, two entry scenarios, and complete integration with IGNY8 platform
|
||
**Dependency:** SAG-Master-Document.md (pure SAG methodology reference)
|
||
**Usage:** Development reference for IGNY8 app, plugin, and AI prompt engineering. Designed for use in development IDE with Claude Code.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Executive Summary](#1-executive-summary)
|
||
2. [Terminology](#2-terminology)
|
||
3. [The Problem SAG Solves in IGNY8](#3-the-problem-sag-solves-in-igny8)
|
||
4. [Three-Layer SAG Architecture](#4-three-layer-sag-architecture)
|
||
5. [Layer 1: Attribute Framework](#5-layer-1-attribute-framework)
|
||
6. [Layer 2: Attribute Population](#6-layer-2-attribute-population)
|
||
7. [Layer 3: Cluster Formation & Keyword Generation](#7-layer-3-cluster-formation--keyword-generation)
|
||
8. [Case 1: Existing Site Intelligence](#8-case-1-existing-site-intelligence)
|
||
9. [Case 2: New Site from Scratch](#9-case-2-new-site-from-scratch)
|
||
10. [The SAG Blueprint](#10-the-sag-blueprint)
|
||
11. [Content Idea Generation from Clusters](#11-content-idea-generation-from-clusters)
|
||
12. [Content Type Mapping Across Platforms](#12-content-type-mapping-across-platforms)
|
||
13. [Taxonomy Creation Flow](#13-taxonomy-creation-flow)
|
||
14. [Integration with IGNY8 Pipeline](#14-integration-with-igny8-pipeline)
|
||
15. [AI Prompt Architecture](#15-ai-prompt-architecture)
|
||
16. [Data Models & Schema](#16-data-models--schema)
|
||
17. [Implementation Phases](#17-implementation-phases)
|
||
|
||
---
|
||
|
||
## 1. Executive Summary
|
||
|
||
IGNY8 currently operates as a keyword-driven content pipeline: users add keywords, AI clusters them by semantic similarity, content is generated and published. This produces functional content but does not produce SAG-quality site architecture. The clustering is flat, has no structural intelligence, and depends entirely on the quality of user keyword selection.
|
||
|
||
This document defines how IGNY8 evolves into a **site architecture engine** that implements the Semantic Authority Grid methodology. The core innovation: site structure is generated from **attribute-based intelligence** — not from keywords. Keywords become an output of the structure, not an input.
|
||
|
||
The system works through three layers:
|
||
- **Layer 1:** Define what attributes organize this sector (e.g., Target Area, Device Type, Relief Focus)
|
||
- **Layer 2:** Populate attribute values from real data (e.g., Foot, Shiatsu, Neuropathy)
|
||
- **Layer 3:** Form clusters from meaningful attribute intersections, auto-generate keywords from those intersections
|
||
|
||
Two entry scenarios feed the same architecture:
|
||
- **Case 1 (Existing Site):** AI extracts attributes and values from real site data (products, categories, content)
|
||
- **Case 2 (New Site):** AI generates attribute framework from sector intelligence + user inputs
|
||
|
||
Both produce a unified **SAG Blueprint** that drives content generation, taxonomy creation, template assignment, internal linking, and backlink planning — without requiring the user to research or add a single keyword.
|
||
|
||
---
|
||
|
||
## 2. Terminology
|
||
|
||
Every term used in this document has exactly one meaning. These align with IGNY8's existing vocabulary where possible and extend it where needed.
|
||
|
||
### 2.1 SAG Architecture Terms
|
||
|
||
| Term | Definition | Example | Becomes in WordPress |
|
||
|------|-----------|---------|---------------------|
|
||
| **Industry** | Top-level business category. Pre-defined in IGNY8. | Health & Wellness, Automotive, Technology | — |
|
||
| **Sector** | Specific niche within an industry. Pre-defined in IGNY8. A site can have 1-5 sectors. | Personal Massagers, Auto Repair, Cloud Services | — |
|
||
| **Attribute** | A classification axis or facet that organizes the sector. Each attribute represents one way to categorize content, products, or services. | Target Area, Device Type, Relief Focus, Therapy Method | Custom taxonomy |
|
||
| **Attribute Value** | A specific option within an attribute. Each value can become a taxonomy term with its own SEO landing page. | Foot, Shiatsu, Neuropathy, Heated, Renpho | Taxonomy term |
|
||
| **Cluster** | A meaningful intersection of 2+ attribute values, forming a self-contained topical ecosystem. Each cluster has a hub page and supporting content. | Foot × Neuropathy = "Foot Massagers for Neuropathy" | IGNY8 Cluster taxonomy term |
|
||
| **Keyword** | A search term that real users type into search engines. Keywords naturally emerge from attribute value combinations within clusters, or are manually added and mapped to clusters. | "foot massager for neuropathy", "best ems foot massager nerve pain" | Target keyword for content |
|
||
|
||
### 2.2 IGNY8 Content Terms (Existing — Preserved)
|
||
|
||
| Term | Definition | Example | Notes |
|
||
|------|-----------|---------|-------|
|
||
| **Sector** | Already exists in IGNY8 Ideas/Content system. Content is tagged with its sector. | Printing Services, Personal Massagers | No change needed |
|
||
| **Structure** | Content format/approach. Determines how the content is written. | Comparison, Guide Tutorial, How To, Question, Review, Top Listicle | Already exists in IGNY8 Ideas UI |
|
||
| **Type** | What kind of page/content this is. Determines the WordPress post type and page template. | Blog Post, Cluster Hub Page, Product Page, Attribute Term Page, Category Page, Service Page | Extends current Post/Page to include all SAG content types |
|
||
| **Cluster** | Already exists in IGNY8 Ideas/Content system. Content is tagged with its cluster. | "UK Sign Shops and Local Sign Making Services" | Enhanced: now generated from attribute intersections instead of keyword grouping |
|
||
|
||
### 2.3 The Complete Hierarchy
|
||
|
||
```
|
||
Industry
|
||
└── Sector(s)
|
||
└── Attributes (classification axes for the sector)
|
||
└── Attribute Values (specific options per attribute)
|
||
└── Clusters (meaningful intersections of 2+ attribute values)
|
||
└── Keywords (emerge naturally from cluster's attribute combination)
|
||
└── Content Ideas (specific content pieces with Structure + Type)
|
||
└── Content (generated articles, pages, products)
|
||
```
|
||
|
||
### 2.4 What Changed from Current IGNY8
|
||
|
||
| Current IGNY8 | SAG-Enhanced IGNY8 |
|
||
|--------------|-------------------|
|
||
| Industry/Sector = keyword database filter only | Industry/Sector = carries attribute framework (NEW data layer) |
|
||
| Clusters formed from keyword grouping | Clusters formed from attribute value intersections |
|
||
| Keywords must be added first, structure follows | Structure comes first, keywords emerge from it |
|
||
| All clusters produce same content type | Clusters have types that determine content structure |
|
||
| No custom taxonomy generation | Attributes become WordPress custom taxonomies automatically |
|
||
| Sector has no structural intelligence | Sector carries complete attribute definitions |
|
||
|
||
---
|
||
|
||
## 3. The Problem SAG Solves in IGNY8
|
||
|
||
### 3.1 Current State
|
||
|
||
IGNY8's existing clustering takes user-provided keywords and groups them by semantic similarity using AI. This works for content writing — keywords get organized, ideas get generated, articles get written. But it fails at site architecture because:
|
||
|
||
1. **Structure depends on keyword quality.** A user who selects incomplete keywords gets an incomplete site structure. The architecture is only as good as the keyword input.
|
||
|
||
2. **No attribute awareness.** The system doesn't know that "Massager Type" and "Relief Focus" are fundamental organizing axes for a massager site. It just sees keywords as flat text.
|
||
|
||
3. **No cluster types.** Every cluster produces the same kind of output. A product category cluster, a condition/problem cluster, and a brand comparison cluster all get treated identically.
|
||
|
||
4. **No taxonomy derivation.** IGNY8 creates IGNY8 Sectors and IGNY8 Clusters as WordPress taxonomies, but it doesn't create the product attributes and custom taxonomies (Massager Type, Relief Focus, Therapy Method) that make a site dimensionally rich. Those were manually created on MassagerSmart.
|
||
|
||
5. **No keyword-free operation.** Without keywords, IGNY8 can't do anything. The entire pipeline stalls at step 1.
|
||
|
||
### 3.2 Target State
|
||
|
||
After SAG implementation, IGNY8 will:
|
||
|
||
- Generate a complete site architecture from sector selection alone — no keywords needed
|
||
- Auto-generate 300-500+ keyword variants from attribute value combinations
|
||
- Form clusters from attribute intersections with proper type classification
|
||
- Create WordPress custom taxonomies from attributes automatically
|
||
- Generate content ideas per cluster with correct Structure and Type
|
||
- Produce different content for different cluster types (hub pages, blog posts, product pages, term pages)
|
||
- Allow users to add more keywords that map into the pre-existing structure
|
||
- Work identically across WordPress, and in future Shopify and custom sites (same concepts, platform-specific terminology)
|
||
|
||
---
|
||
|
||
## 4. Three-Layer SAG Architecture
|
||
|
||
### 4.1 Overview
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ LAYER 1: ATTRIBUTE FRAMEWORK │
|
||
│ │
|
||
│ "What attributes organize this sector?" │
|
||
│ │
|
||
│ Input: Industry + Sector(s) │
|
||
│ Output: Attribute definitions (axes without values) │
|
||
│ Source: New attribute data layer (to be built) + AI generation │
|
||
│ │
|
||
│ Example output: │
|
||
│ Attributes: [Target Area, Device Type, Relief Focus, │
|
||
│ Therapy Method, Brand, Features] │
|
||
└──────────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ LAYER 2: ATTRIBUTE POPULATION │
|
||
│ │
|
||
│ "What specific values exist for each attribute?" │
|
||
│ │
|
||
│ Input: Attribute framework + real-world data │
|
||
│ Output: Attributes with populated values │
|
||
│ Source: Site data (Case 1) OR user inputs (Case 2) + AI │
|
||
│ │
|
||
│ Example output: │
|
||
│ Target Area: [Foot, Neck, Face] │
|
||
│ Device Type: [Shiatsu, EMS, Heated, Percussion] │
|
||
│ Relief Focus: [Neuropathy, Plantar Fasciitis, Circulation] │
|
||
└──────────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ LAYER 3: CLUSTER FORMATION & KEYWORD GENERATION │
|
||
│ │
|
||
│ "What clusters form at attribute intersections? │
|
||
│ What keywords naturally emerge from those clusters?" │
|
||
│ │
|
||
│ Input: Populated attributes │
|
||
│ Output: Clusters + auto-generated keywords + content plan │
|
||
│ Source: AI analysis of meaningful intersections │
|
||
│ │
|
||
│ Example output: │
|
||
│ Cluster: Foot × Neuropathy │
|
||
│ → Hub: "Best Foot Massagers for Neuropathy" │
|
||
│ → Keywords: "foot massager for neuropathy", │
|
||
│ "best foot massager neuropathy", │
|
||
│ "ems foot massager nerve pain", ... │
|
||
│ → Supporting content: 4-6 blog topics │
|
||
└──────────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ SAG BLUEPRINT │
|
||
│ │
|
||
│ Complete site architecture: Clusters (typed) + Taxonomies + │
|
||
│ Keywords + Content plan + URL structure + Internal linking map │
|
||
│ │
|
||
│ → Feeds IGNY8 Pipeline: Ideas → Writer → Images → Publish → Link │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 Key Principle: Attributes Before Everything
|
||
|
||
**Current IGNY8 flow:**
|
||
User adds keywords → AI clusters keywords → Ideas → Content
|
||
|
||
**SAG flow:**
|
||
Sector selected → Attributes defined → Values populated → Clusters form at intersections → Keywords auto-generated → Ideas created per cluster → Content generated per type → Published → Interlinked
|
||
|
||
The user never needs to add a keyword. The system generates its own keyword base from the attribute structure. Users CAN add keywords to enhance coverage, but the system operates independently of manual keyword input.
|
||
|
||
---
|
||
|
||
## 5. Layer 1: Attribute Framework
|
||
|
||
### 5.1 What Layer 1 Provides
|
||
|
||
Layer 1 answers: "For this sector, what are the natural classification axes?"
|
||
|
||
This is sector-level knowledge. You don't need keywords or products to know that a massager e-commerce site will have attributes like Target Area, Device Type, Relief Focus, and Brand. You don't need keywords to know that a law firm will have attributes like Practice Area, Case Type, Client Type, and Location.
|
||
|
||
### 5.2 Current State: No Attribute Data Exists
|
||
|
||
**Critical clarification:** IGNY8's current industry/sector system is a flat classification used only to filter the keyword database. Selecting "Health & Wellness → Personal Massagers" currently provides zero structural intelligence — no attributes, no values, no cluster patterns.
|
||
|
||
**Layer 1 requires building a completely new data layer** that attaches attribute definitions to each sector. This is a significant new effort, not an extension of existing sector data.
|
||
|
||
### 5.3 Attribute Data Structure
|
||
|
||
Each sector has an attribute framework definition:
|
||
|
||
```json
|
||
{
|
||
"sector": "Personal Massagers",
|
||
"industry": "Health & Wellness",
|
||
"site_type": "e-commerce",
|
||
"attributes": [
|
||
{
|
||
"name": "Target Area",
|
||
"description": "Body area the device targets",
|
||
"level": "primary",
|
||
"suggested_values": ["Neck", "Back", "Foot", "Face", "Eye", "Scalp", "Shoulder", "Full Body"]
|
||
},
|
||
{
|
||
"name": "Device Type",
|
||
"description": "Technology or mechanism of the massager",
|
||
"level": "primary",
|
||
"suggested_values": ["Shiatsu", "EMS", "Percussion", "Vibration", "Roller", "LED", "Microcurrent", "Heated"]
|
||
},
|
||
{
|
||
"name": "Relief Focus",
|
||
"description": "Health condition or therapeutic goal",
|
||
"level": "secondary",
|
||
"suggested_values": ["Neuropathy", "Plantar Fasciitis", "Circulation", "Pain Relief", "Muscle Recovery", "Skin Tightening"]
|
||
},
|
||
{
|
||
"name": "Therapy Method",
|
||
"description": "Therapeutic approach or technique",
|
||
"level": "secondary",
|
||
"suggested_values": ["Electrical Stimulation", "Deep Tissue", "Kneading", "TENS Therapy", "NMES Therapy", "Heat Therapy"]
|
||
},
|
||
{
|
||
"name": "Brand",
|
||
"description": "Manufacturer or brand name",
|
||
"level": "tertiary",
|
||
"suggested_values": []
|
||
},
|
||
{
|
||
"name": "Features",
|
||
"description": "Product features and characteristics",
|
||
"level": "tertiary",
|
||
"suggested_values": ["Cordless", "Portable", "Waterproof", "Rechargeable"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.4 Attribute Levels
|
||
|
||
| Level | Purpose | WordPress Mapping | Content Impact |
|
||
|-------|---------|------------------|----------------|
|
||
| **Primary** | Main site navigation axes. Define the top-level structure. | Hierarchical category or main custom taxonomy | Category pages, primary URL segments |
|
||
| **Secondary** | Important classification that creates cluster depth. | Custom taxonomy (non-hierarchical) | Cluster formation axes, attribute term landing pages |
|
||
| **Tertiary** | Descriptive attributes for filtering and tagging. | Tags or flat custom taxonomy | Product filters, content tags, minor landing pages |
|
||
|
||
### 5.5 Building the Attribute Data Layer
|
||
|
||
**Phase 1: Manual Creation (High Quality)**
|
||
For the 12+ industries already in IGNY8 with their 60-120 sector combinations, attribute frameworks are manually crafted. This is the gold standard — each sector gets a reviewed, validated attribute definition.
|
||
|
||
**Phase 2: AI-Assisted Generation**
|
||
For new industries/sectors not covered by manual creation, AI generates attribute frameworks using:
|
||
- Sector knowledge from training data
|
||
- Pattern matching from similar manually-created sector frameworks
|
||
- Competitive intelligence (analyzing top-ranking sites in the sector)
|
||
|
||
**Phase 3: User-Contributed Refinement**
|
||
Users can add custom attributes during setup. Over time, commonly-added custom attributes get promoted to the sector's default framework.
|
||
|
||
### 5.6 Multi-Sector Attribute Merging
|
||
|
||
When a site has multiple sectors (e.g., "Auto Repair" + "Electric Vehicles"):
|
||
|
||
1. **Identical attributes combine** — both have "Vehicle Type" → merge value lists
|
||
2. **Unique attributes add** — "Battery Technology" from EV sector adds as sector-specific attribute
|
||
3. **Cross-sector clusters can form** — intersections that span both sectors create unique content opportunities (e.g., "Electric Vehicle Brake Repair")
|
||
|
||
---
|
||
|
||
## 6. Layer 2: Attribute Population
|
||
|
||
### 6.1 What Layer 2 Provides
|
||
|
||
Layer 1 gives the axes — "this sector has Target Area, Device Type, Relief Focus." Layer 2 fills in the actual values — "THIS site's Target Area values are Foot, Neck, and Face (not Back, Eye, or Scalp)."
|
||
|
||
### 6.2 Population Sources by Scenario
|
||
|
||
**Case 1 (Existing Site):**
|
||
The IGNY8 plugin sends product/content data from the WordPress site. AI analyzes product titles, descriptions, existing categories, and existing attributes to extract what values actually exist.
|
||
|
||
A product titled "Nekteck Shiatsu Neck and Back Massager with Heat" tells the AI:
|
||
- Target Area values: Neck, Back
|
||
- Device Type values: Shiatsu
|
||
- Feature values: Heated
|
||
- Brand values: Nekteck
|
||
|
||
Across 50 products, the AI builds the complete value set for each attribute.
|
||
|
||
**Case 2 (New Site):**
|
||
Values come from user inputs during setup ("What body areas do your products target?", "What device types do you sell?"), supplemented by the sector framework's suggested values. The user confirms, prunes, or adds to suggestions.
|
||
|
||
### 6.3 Right-Sizing to the Site
|
||
|
||
The sector framework might suggest 8 Target Area values, but a specific site only sells foot and neck massagers. Layer 2 prunes to just Foot and Neck. This dramatically simplifies the resulting structure — fewer clusters, fewer taxonomy terms, fewer pages — all perfectly matched to the actual business.
|
||
|
||
**Pruning rules:**
|
||
- Primary attribute with only 1 value → demote to secondary (the entire site is about that one thing, so it's not a differentiating axis)
|
||
- Secondary attribute with only 1 value → demote to tertiary
|
||
- Tertiary attribute with 0 values → exclude entirely
|
||
- User always has final override
|
||
|
||
### 6.4 Completeness Assessment
|
||
|
||
After population, each attribute gets a readiness score:
|
||
|
||
| Score | Meaning | Action |
|
||
|-------|---------|--------|
|
||
| **Ready** | 3+ values populated | Proceed to cluster formation |
|
||
| **Thin** | 1-2 values only | AI suggests additions; user confirms |
|
||
| **Empty** | No values | Attribute excluded from blueprint OR user prompted |
|
||
|
||
All primary attributes must be "Ready" before the SAG Blueprint can be generated.
|
||
|
||
---
|
||
|
||
## 7. Layer 3: Cluster Formation & Keyword Generation
|
||
|
||
### 7.1 How Clusters Form
|
||
|
||
Clusters are **meaningful intersections of 2+ attribute values**. Not every mathematical combination becomes a cluster — only intersections that represent a real topical ecosystem with enough depth to support a hub page and supporting content.
|
||
|
||
**Example: Given these populated attributes:**
|
||
- Target Area: [Foot, Neck, Face]
|
||
- Device Type: [Shiatsu, EMS, Heated]
|
||
- Relief Focus: [Neuropathy, Plantar Fasciitis, Circulation]
|
||
|
||
**Potential 2-value intersections (Target Area × Relief Focus):**
|
||
- Foot × Neuropathy → ✅ Strong cluster: "Foot Massagers for Neuropathy"
|
||
- Foot × Plantar Fasciitis → ✅ Strong cluster: "Foot Massagers for Plantar Fasciitis"
|
||
- Foot × Circulation → ✅ Viable cluster: "Foot Massagers for Circulation"
|
||
- Neck × Neuropathy → ❌ Weak: not enough product/search reality
|
||
- Face × Circulation → ❌ Weak: too niche for standalone cluster
|
||
|
||
**Potential 2-value intersections (Target Area × Device Type):**
|
||
- Foot × Shiatsu → ✅ Strong cluster: "Shiatsu Foot Massagers"
|
||
- Foot × EMS → ✅ Strong cluster: "EMS Foot Massagers"
|
||
- Neck × Heated → ✅ Strong cluster: "Heated Neck Massagers"
|
||
- Face × LED → ✅ Strong cluster: "LED Face Massagers"
|
||
|
||
**Potential 3-value intersections:**
|
||
- Foot × EMS × Neuropathy → Could be a cluster if deep enough, or a supporting content piece within the "Foot × Neuropathy" cluster
|
||
|
||
**The AI determines which intersections warrant standalone clusters** based on:
|
||
- Does this intersection represent a real product/service category?
|
||
- Can it support a hub page with 3-10 supporting content pieces?
|
||
- Is there enough differentiation from adjacent clusters?
|
||
- Would real users search for this specific intersection?
|
||
|
||
### 7.2 Cluster Types
|
||
|
||
Each cluster gets a type classification based on what its attribute intersection represents:
|
||
|
||
| Cluster Type | What It Represents | Hub Page Becomes | Example |
|
||
|-------------|-------------------|-----------------|---------|
|
||
| **Product/Service Category** | Primary attribute intersection defining a product/service group | Category page or cluster hub landing page | "Shiatsu Foot Massagers" |
|
||
| **Condition/Problem** | Intersection involving a problem/need attribute | Cluster hub — solution-focused landing page | "Foot Massagers for Neuropathy" |
|
||
| **Feature** | Intersection highlighting a specific feature/technology | Feature landing page | "Heated Neck Massagers for Circulation" |
|
||
| **Brand** | Grouping by brand across products/services | Brand comparison page | "Top Foot Massager Brands Compared" |
|
||
| **Informational** | Educational/how-to content supporting a broader topic | Blog hub or guide page | "How to Massage Your Neck" |
|
||
| **Comparison** | Head-to-head or buying guide content | Comparison/roundup article | "EMS vs TENS: Which Therapy Works Better?" |
|
||
|
||
### 7.3 Keyword Auto-Generation
|
||
|
||
This is the breakthrough: **keywords emerge from attribute value combinations without manual research.**
|
||
|
||
**Process:**
|
||
For each cluster, take its attribute values and generate natural keyword variants:
|
||
|
||
**Cluster: Foot × Neuropathy (Condition/Problem type)**
|
||
|
||
Attribute values in this cluster: Target Area=Foot, Relief Focus=Neuropathy
|
||
|
||
**Auto-generated keyword variants:**
|
||
```
|
||
Direct combinations:
|
||
"foot massager for neuropathy"
|
||
"foot massager neuropathy"
|
||
"neuropathy foot massager"
|
||
|
||
With modifiers (best, top, review):
|
||
"best foot massager for neuropathy"
|
||
"best foot massager neuropathy"
|
||
"top foot massager for neuropathy"
|
||
"foot massager for neuropathy reviews"
|
||
|
||
With additional attribute values from the cluster's products:
|
||
"ems foot massager for neuropathy"
|
||
"shiatsu foot massager neuropathy"
|
||
"heated foot massager nerve pain"
|
||
|
||
Question variants:
|
||
"do foot massagers help neuropathy"
|
||
"is foot massager good for neuropathy"
|
||
"what foot massager is best for neuropathy"
|
||
|
||
Long-tail with condition context:
|
||
"foot massager for diabetic neuropathy"
|
||
"foot massager for peripheral neuropathy"
|
||
"doctor recommended foot massager for neuropathy"
|
||
"foot massager for neuropathy pain relief"
|
||
```
|
||
|
||
**From just 2 attribute values (Foot + Neuropathy), 15-25 keyword variants emerge.** Across all clusters for a site with 3 target areas × 3 device types × 3 conditions, you get 300-500+ keyword variants without anyone researching or manually adding a single keyword.
|
||
|
||
### 7.4 Keyword Variant Generation Templates
|
||
|
||
The system uses templates to generate keywords from attribute values:
|
||
|
||
```
|
||
Templates for Condition/Problem clusters:
|
||
"[target] massager for [condition]"
|
||
"best [target] massager for [condition]"
|
||
"[device_type] [target] massager for [condition]"
|
||
"does [target] massager help [condition]"
|
||
"[condition] [target] massager reviews"
|
||
"doctor recommended [target] massager for [condition]"
|
||
|
||
Templates for Product Type clusters:
|
||
"[device_type] [target] massager"
|
||
"best [device_type] [target] massager"
|
||
"[device_type] [target] massager reviews"
|
||
"[device_type] vs [device_type_2] [target] massager"
|
||
|
||
Templates for Brand clusters:
|
||
"[brand] [target] massager"
|
||
"[brand] [target] massager reviews"
|
||
"[brand] vs [brand_2] [target] massager"
|
||
"best [brand] massager"
|
||
```
|
||
|
||
These templates are sector-specific. A services business would use templates like:
|
||
```
|
||
"[service_type] in [location]"
|
||
"best [service_type] near me"
|
||
"[service_type] for [industry]"
|
||
"how much does [service_type] cost"
|
||
```
|
||
|
||
### 7.5 Manual Keyword Addition (Supplementary)
|
||
|
||
Users can still add keywords from:
|
||
- IGNY8's pre-researched keyword library
|
||
- Manual entry
|
||
- CSV import
|
||
- Keyword research API (future)
|
||
|
||
These keywords get **mapped to existing clusters** based on which cluster's attribute intersection they match. If a keyword doesn't match any cluster, it's flagged as either:
|
||
- A gap in the attribute framework (suggest new attribute value)
|
||
- A potential new cluster (suggest new intersection)
|
||
- An outlier (exclude from structure)
|
||
|
||
---
|
||
|
||
## 8. Case 1: Existing Site Intelligence
|
||
|
||
### 8.1 Scenario
|
||
|
||
An existing WordPress/WooCommerce site connects to IGNY8. The site has products, categories, some pages and blog posts — but no SAG structure, weak/flat taxonomies, and no cluster organization.
|
||
|
||
### 8.2 Data Collection
|
||
|
||
The IGNY8 plugin collects and sends to the app:
|
||
|
||
| Data Type | What's Collected | Purpose |
|
||
|-----------|-----------------|---------|
|
||
| **Products** | Title, description, price, existing categories, existing tags, any custom attribute values, images | AI extracts attribute values from product data |
|
||
| **Categories** | Name, slug, hierarchy, description, product count | Understand existing site structure (usually flat/weak) |
|
||
| **Custom Taxonomies** | All registered taxonomies + their terms | Detect if any attributes already exist (partially) |
|
||
| **Pages** | Title, URL, content summary | Identify existing hubs, service pages, landing pages |
|
||
| **Posts** | Title, URL, content summary, categories, tags | Identify existing blog content to map to clusters |
|
||
| **WooCommerce Attributes** | All product attributes + values + assignments | Direct attribute data (if site has any) |
|
||
| **Menu Structure** | Navigation items with hierarchy | Understand how site currently organizes content |
|
||
|
||
### 8.3 AI Attribute Extraction
|
||
|
||
The critical Case 1 intelligence step. AI receives messy, unstructured site data and infers what attributes SHOULD exist.
|
||
|
||
**Example: AI analyzes 50 product titles:**
|
||
```
|
||
"Nekteck Shiatsu Neck and Back Massager with Heat"
|
||
"Cloud Massage Shiatsu Foot Massager Machine"
|
||
"RENPHO Foot Massager with Heat, Shiatsu Deep Kneading"
|
||
"EMS Foot Massager Pad for Neuropathy Pain Relief"
|
||
"Portable Neck Massager for Pain Relief"
|
||
"Heated Back Massager with Vibration"
|
||
...
|
||
```
|
||
|
||
**AI extraction output:**
|
||
```
|
||
Discovered Attributes:
|
||
Target Area: Neck (found 12x), Back (found 8x), Foot (found 25x), Shoulder (found 5x)
|
||
Device Type: Shiatsu (18x), EMS (7x), Percussion (3x), Vibration (4x)
|
||
Relief Focus: Neuropathy (5x), Pain Relief (12x), Circulation (3x)
|
||
Brand: Nekteck (5), RENPHO (8), Cloud Massage (3), Homedics (4), ...
|
||
Features: Heated (15x), Cordless (7x), Portable (4x)
|
||
|
||
Confidence: High — clear recurring patterns across products
|
||
```
|
||
|
||
The AI compares these discovered attributes against the sector template (if available for this sector) to validate its findings and suggest any attributes the product data missed.
|
||
|
||
### 8.4 Gap Analysis
|
||
|
||
After attribute extraction and cluster formation, the system reports:
|
||
|
||
```
|
||
YOUR SITE CURRENTLY HAS:
|
||
50 products in 3 flat categories
|
||
12 tags (unorganized)
|
||
0 custom product attributes
|
||
8 random blog posts
|
||
5 static pages
|
||
|
||
SAG BLUEPRINT RECOMMENDS:
|
||
6 attributes → become 6 WordPress custom taxonomies
|
||
18 attribute values → become 18 taxonomy terms with landing pages
|
||
12 cluster hubs → new authority pages to create
|
||
36+ supporting blog posts → organized by cluster
|
||
Internal linking across all 100+ pages
|
||
|
||
GAP: 12 cluster hubs, 28+ blog posts, 18 term pages,
|
||
50 products need attribute enrichment,
|
||
250+ internal links to create
|
||
```
|
||
|
||
### 8.5 Product Auto-Tagging
|
||
|
||
For Case 1, existing products lack dimensional attributes. The system auto-tags:
|
||
|
||
1. AI reads each product's title and description
|
||
2. Identifies which attribute values the product belongs to
|
||
3. Generates bulk taxonomy term assignments
|
||
4. User reviews before saving
|
||
|
||
**Example:**
|
||
"RENPHO Foot Massager with Heat, Shiatsu Deep Kneading" →
|
||
- Target Area: Foot
|
||
- Device Type: Shiatsu
|
||
- Features: Heated
|
||
- Brand: RENPHO
|
||
- Therapy Method: Deep Tissue, Kneading
|
||
|
||
---
|
||
|
||
## 9. Case 2: New Site from Scratch
|
||
|
||
### 9.1 Scenario
|
||
|
||
A user creates a new site in IGNY8 with no existing content. They go through the Setup Wizard and IGNY8 generates the complete SAG architecture before any content exists.
|
||
|
||
### 9.2 Updated Setup Wizard
|
||
|
||
```
|
||
Step 1: Welcome
|
||
→ Standard welcome screen (no changes)
|
||
|
||
Step 2: Add Site
|
||
→ Site Name, URL, Industry, Sectors (up to 5)
|
||
→ (Existing step — no changes needed)
|
||
|
||
Step 3: Site Structure (NEW STEP)
|
||
→ 3a: AI generates attribute framework from sector
|
||
→ 3b: User reviews attributes, toggles on/off, edits values
|
||
→ 3c: User provides business specifics:
|
||
- What products/services? (per site type)
|
||
- What conditions/problems do they solve?
|
||
- What brands? (if e-commerce)
|
||
- What locations? (if services)
|
||
→ 3d: AI populates attributes from user input
|
||
→ 3e: Blueprint preview — clusters, keywords, content plan
|
||
→ 3f: User confirms → Blueprint generated
|
||
|
||
Step 4: Connect WordPress
|
||
→ Standard connection
|
||
→ ENHANCED: Plugin auto-creates taxonomies from blueprint
|
||
|
||
Step 5: Keywords (now optional)
|
||
→ Keywords from library can supplement auto-generated keywords
|
||
→ Gap analysis shows which clusters need more coverage
|
||
→ User can skip entirely — auto-generated keywords are sufficient
|
||
|
||
Step 6: Complete
|
||
→ Blueprint summary, content plan, "Start generating" CTA
|
||
```
|
||
|
||
### 9.3 Quick Mode vs Detailed Mode
|
||
|
||
**Quick Mode:** "Let IGNY8 build your site structure automatically"
|
||
- Uses sector template defaults
|
||
- Skips attribute review
|
||
- Generates blueprint from defaults
|
||
- User can refine later in Site Settings
|
||
|
||
**Detailed Mode:** "Customize your site structure"
|
||
- Full attribute review and business input flow
|
||
- More accurate, tailored blueprint
|
||
- Recommended for specific niches
|
||
|
||
### 9.4 Step 3 UI Flow
|
||
|
||
**Screen: Attribute Review**
|
||
```
|
||
Based on your sector (Personal Massagers), we've identified
|
||
these organizing attributes for your site:
|
||
|
||
PRIMARY ATTRIBUTES:
|
||
✅ Target Area
|
||
Values: [Neck] [Foot] [Face] [Back] [+ Add]
|
||
✅ Device Type
|
||
Values: [Shiatsu] [EMS] [Heated] [Percussion] [+ Add]
|
||
|
||
SECONDARY ATTRIBUTES:
|
||
✅ Relief Focus
|
||
Values: [Neuropathy] [Plantar Fasciitis] [Circulation] [+ Add]
|
||
✅ Therapy Method
|
||
Values: [Deep Tissue] [TENS] [NMES] [Heat Therapy] [+ Add]
|
||
|
||
TERTIARY ATTRIBUTES:
|
||
☑ Brand — [Add your brands]
|
||
☑ Features — [Cordless] [Portable] [Waterproof]
|
||
|
||
[+ Add Custom Attribute]
|
||
[Continue →]
|
||
```
|
||
|
||
**Screen: Blueprint Preview**
|
||
```
|
||
Your Site Architecture
|
||
|
||
12 Clusters identified across 3 categories:
|
||
|
||
📁 Foot Massagers
|
||
├── Foot Massagers for Neuropathy (Condition cluster, Hub page)
|
||
├── Foot Massagers for Plantar Fasciitis (Condition cluster, Hub page)
|
||
├── Shiatsu Foot Massagers (Product Type cluster, Hub page)
|
||
├── EMS Foot Massagers (Product Type cluster, Hub page)
|
||
└── Foot Massager Brands Compared (Brand cluster, Blog post)
|
||
|
||
📁 Neck Massagers
|
||
├── Heated Neck Massagers (Feature cluster, Hub page)
|
||
├── Shiatsu Neck Massagers (Product Type cluster, Hub page)
|
||
└── Neck Massager Brands Compared (Brand cluster, Blog post)
|
||
|
||
📁 Face Massagers
|
||
├── LED Face Massagers (Product Type cluster, Hub page)
|
||
├── Microcurrent Face Massagers (Product Type cluster, Hub page)
|
||
└── Face Massager Brands Compared (Brand cluster, Blog post)
|
||
|
||
📊 420 keywords auto-generated
|
||
📝 48 content pieces planned (12 hubs + 36 supporting)
|
||
🏷️ 6 custom taxonomies to create
|
||
🔗 Internal linking map ready
|
||
|
||
[✅ Approve & Build] [↩ Adjust Attributes]
|
||
```
|
||
|
||
---
|
||
|
||
## 10. The SAG Blueprint
|
||
|
||
### 10.1 What the Blueprint Contains
|
||
|
||
Both Case 1 and Case 2 produce the same output: the SAG Blueprint. This is the master architectural document for the site.
|
||
|
||
```json
|
||
{
|
||
"blueprint_id": "uuid",
|
||
"site_id": "site_uuid",
|
||
"version": 1,
|
||
"status": "active",
|
||
|
||
"attributes": [
|
||
{
|
||
"name": "Target Area",
|
||
"slug": "target-area",
|
||
"level": "primary",
|
||
"values": [
|
||
{"name": "Foot", "slug": "foot"},
|
||
{"name": "Neck", "slug": "neck"},
|
||
{"name": "Face", "slug": "face"}
|
||
]
|
||
},
|
||
{
|
||
"name": "Device Type",
|
||
"slug": "device-type",
|
||
"level": "primary",
|
||
"values": [
|
||
{"name": "Shiatsu", "slug": "shiatsu"},
|
||
{"name": "EMS", "slug": "ems"},
|
||
{"name": "Heated", "slug": "heated"}
|
||
]
|
||
},
|
||
{
|
||
"name": "Relief Focus",
|
||
"slug": "relief-focus",
|
||
"level": "secondary",
|
||
"values": [
|
||
{"name": "Neuropathy", "slug": "neuropathy"},
|
||
{"name": "Plantar Fasciitis", "slug": "plantar-fasciitis"},
|
||
{"name": "Circulation", "slug": "circulation"}
|
||
]
|
||
}
|
||
],
|
||
|
||
"clusters": [
|
||
{
|
||
"name": "Foot Massagers for Neuropathy",
|
||
"cluster_type": "condition_problem",
|
||
"attribute_intersection": {
|
||
"target_area": "Foot",
|
||
"relief_focus": "Neuropathy"
|
||
},
|
||
"hub_page": {
|
||
"title": "Best Foot Massagers for Neuropathy & Nerve Pain Relief",
|
||
"type": "cluster_hub",
|
||
"structure": "guide_tutorial",
|
||
"url_slug": "/best-foot-massagers-for-neuropathy-nerve-pain-relief/"
|
||
},
|
||
"auto_generated_keywords": [
|
||
"foot massager for neuropathy",
|
||
"best foot massager for neuropathy",
|
||
"neuropathy foot massager",
|
||
"doctor recommended foot massager for neuropathy",
|
||
"ems foot massager for neuropathy",
|
||
"does foot massager help neuropathy"
|
||
],
|
||
"supporting_content": [
|
||
{
|
||
"title": "Doctor-Recommended Foot Massagers for Neuropathy",
|
||
"type": "blog_post",
|
||
"structure": "review",
|
||
"keywords": ["doctor recommended foot massager for neuropathy"]
|
||
},
|
||
{
|
||
"title": "EMS vs TENS for Neuropathy: Which Therapy Works Better?",
|
||
"type": "blog_post",
|
||
"structure": "comparison",
|
||
"keywords": ["ems vs tens neuropathy", "ems foot massager neuropathy"]
|
||
}
|
||
],
|
||
"linked_attribute_terms": ["neuropathy", "ems", "foot"],
|
||
"cross_cluster_links": ["ems-foot-massagers"]
|
||
}
|
||
],
|
||
|
||
"taxonomy_creation_plan": [
|
||
{
|
||
"attribute": "Target Area",
|
||
"wp_taxonomy_slug": "target-area",
|
||
"register_for": ["product", "post", "page"],
|
||
"terms_to_create": ["Foot", "Neck", "Face"]
|
||
},
|
||
{
|
||
"attribute": "Device Type",
|
||
"wp_taxonomy_slug": "device-type",
|
||
"register_for": ["product"],
|
||
"terms_to_create": ["Shiatsu", "EMS", "Heated"]
|
||
}
|
||
],
|
||
|
||
"internal_linking_map": {
|
||
"rules_reference": "SAG-Interlinking-Specification.md"
|
||
},
|
||
|
||
"execution_priority": [
|
||
{"phase": 1, "items": ["category_pages", "top_cluster_hubs"]},
|
||
{"phase": 2, "items": ["remaining_hubs", "first_blogs_per_cluster"]},
|
||
{"phase": 3, "items": ["attribute_term_pages", "product_enrichment"]},
|
||
{"phase": 4, "items": ["additional_blogs", "brand_comparisons"]}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 10.2 Blueprint Lifecycle
|
||
|
||
| State | Description |
|
||
|-------|-------------|
|
||
| **Draft** | Generated, awaiting user confirmation |
|
||
| **Active** | Confirmed, driving all content operations |
|
||
| **Evolving** | New clusters added as products/content grows |
|
||
| **Archived** | Replaced by newer version |
|
||
|
||
Blueprints are versioned, not overwritten. Site changes trigger new versions.
|
||
|
||
---
|
||
|
||
## 11. Content Idea Generation from Clusters
|
||
|
||
### 11.1 Mapping to IGNY8's Existing Content Ideas System
|
||
|
||
IGNY8 already has a Content Ideas system with these fields (visible in the Ideas UI):
|
||
- **Content Idea Title** — the article/page title
|
||
- **Sector** — which sector this belongs to
|
||
- **Structure** — content format (Comparison, Guide Tutorial, How To, Question, Review, Top Listicle)
|
||
- **Type** — content type (Post, Page — extending to include all SAG types)
|
||
- **Primary Keywords** — target keywords for this content
|
||
- **Cluster** — which cluster this belongs to
|
||
|
||
SAG enhances this system by:
|
||
1. Auto-generating ideas from the blueprint (instead of only from keyword clustering)
|
||
2. Setting the correct **Type** based on cluster type and content purpose
|
||
3. Setting the correct **Structure** based on the content's role in the cluster
|
||
4. Pre-assigning **Cluster** from the blueprint
|
||
5. Pre-populating **Primary Keywords** from auto-generated keywords
|
||
|
||
### 11.2 Type Field — Extended Content Types
|
||
|
||
The existing Type field (Post, Page) needs to expand to cover all SAG content types. These are platform-agnostic concepts that map differently per CMS:
|
||
|
||
| SAG Content Type | Purpose | WordPress | Shopify (future) | Custom Site (future) |
|
||
|-----------------|---------|-----------|------------------|---------------------|
|
||
| **Blog Post** | Supporting cluster content — articles, guides, comparisons | `post` | Blog article | `/blog/[slug]` |
|
||
| **Cluster Hub Page** | Authority landing page for a cluster | `page` (with hub template) | Page | `/[slug]` |
|
||
| **Product Page** | Individual product (e-commerce) | `product` (WooCommerce) | Product | `/products/[slug]` |
|
||
| **Service Page** | Individual service offering | `page` (with service template) | Page | `/services/[slug]` |
|
||
| **Category Page** | Top-level product/content category | Category term (with rich content) | Collection | `/[category]` |
|
||
| **Attribute Term Page** | Landing page for an attribute value | Custom taxonomy term (with rich content) | Tag/Collection | `/[attribute]/[value]` |
|
||
| **Brand Page** | Brand overview or comparison | `post` or `page` | Page | `/brands/[slug]` |
|
||
| **Comparison Page** | Head-to-head or roundup | `post` | Blog article | `/blog/[slug]` |
|
||
|
||
### 11.3 Structure Field — Content Format per Type
|
||
|
||
The existing Structure field determines HOW the content is written. SAG assigns structures based on cluster type and content purpose:
|
||
|
||
| Cluster Type | Hub Page Structure | Supporting Blog Structures |
|
||
|-------------|-------------------|---------------------------|
|
||
| Condition/Problem | Guide Tutorial | How To, Review, Comparison, Question |
|
||
| Product Type | Top Listicle or Guide Tutorial | Comparison, Review, How To |
|
||
| Feature | Guide Tutorial | Comparison, How To, Question |
|
||
| Brand | Comparison or Review | Review, Comparison |
|
||
| Informational | How To or Guide Tutorial | How To, Question, Guide Tutorial |
|
||
| Comparison | Comparison | Review, Question |
|
||
|
||
### 11.4 Idea Generation Logic
|
||
|
||
For each cluster in the blueprint, the system generates:
|
||
|
||
**1 Hub Page Idea:**
|
||
```
|
||
Title: "Best Foot Massagers for Neuropathy & Nerve Pain Relief"
|
||
Sector: Personal Massagers
|
||
Structure: Guide Tutorial
|
||
Type: Cluster Hub Page
|
||
Keywords: foot massager for neuropathy, best foot massager for neuropathy, neuropathy foot massager
|
||
Cluster: Foot Massagers for Neuropathy
|
||
```
|
||
|
||
**3-6 Supporting Content Ideas:**
|
||
```
|
||
Title: "Doctor-Recommended Foot Massagers for Neuropathy"
|
||
Sector: Personal Massagers
|
||
Structure: Review
|
||
Type: Blog Post
|
||
Keywords: doctor recommended foot massager for neuropathy
|
||
Cluster: Foot Massagers for Neuropathy
|
||
```
|
||
|
||
```
|
||
Title: "EMS vs TENS for Neuropathy: Which Therapy Works Better?"
|
||
Sector: Personal Massagers
|
||
Structure: Comparison
|
||
Type: Blog Post
|
||
Keywords: ems vs tens neuropathy
|
||
Cluster: Foot Massagers for Neuropathy
|
||
```
|
||
|
||
```
|
||
Title: "Does a Foot Massager Actually Help Neuropathy?"
|
||
Sector: Personal Massagers
|
||
Structure: Question
|
||
Type: Blog Post
|
||
Keywords: does foot massager help neuropathy
|
||
Cluster: Foot Massagers for Neuropathy
|
||
```
|
||
|
||
**Attribute Term Page Ideas (from cluster's linked attributes):**
|
||
```
|
||
Title: "Neuropathy Relief: Best Devices & Therapy Options"
|
||
Sector: Personal Massagers
|
||
Structure: Guide Tutorial
|
||
Type: Attribute Term Page
|
||
Keywords: neuropathy relief devices, neuropathy therapy
|
||
Cluster: (cross-cluster — serves multiple neuropathy-related clusters)
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Content Type Mapping Across Platforms
|
||
|
||
### 12.1 Platform-Agnostic Concept
|
||
|
||
SAG defines content types by their role in the architecture, not by platform-specific terminology. The same cluster hub concept exists on WordPress, Shopify, and custom sites — only the implementation differs.
|
||
|
||
### 12.2 Mapping Table
|
||
|
||
| SAG Concept | WordPress | Shopify (future) | Custom React/HTML (future) |
|
||
|------------|-----------|------------------|---------------------------|
|
||
| **Blog Post** | Post (`post`) | Blog Article | Page component at `/blog/[slug]` |
|
||
| **Cluster Hub** | Page (`page`) with custom template | Page with custom template | Page component at `/[slug]` |
|
||
| **Product** | WooCommerce Product (`product`) | Product | Page component at `/products/[slug]` |
|
||
| **Service** | Page (`page`) with service template | Page | Page component at `/services/[slug]` |
|
||
| **Category** | Category term with description content | Collection | Route at `/[category]` |
|
||
| **Attribute Term** | Custom taxonomy term with description content | Metafield-based tag or collection | Route at `/[attribute]/[value]` |
|
||
| **Navigation** | WordPress Menus | Navigation menus | React Router / Nav component |
|
||
| **Taxonomy** | `register_taxonomy()` | Collections, Tags, Metafields | Database model + routes |
|
||
| **Attribute on Product** | Product attribute / custom taxonomy term | Product metafield or variant option | Product property in database |
|
||
|
||
### 12.3 Implementation Priority
|
||
|
||
1. **WordPress** — primary platform, implemented first
|
||
2. **Custom Site** — React/HTML site builder (parallel development possible)
|
||
3. **Shopify** — future phase, after WordPress and Custom are proven
|
||
|
||
### 12.4 Abstraction Layer
|
||
|
||
IGNY8 should store content types in platform-agnostic format (the SAG Content Type) and translate to platform-specific format only at the publishing step. This means:
|
||
|
||
- Blueprint uses SAG types: `cluster_hub`, `blog_post`, `product_page`, `attribute_term_page`
|
||
- Writer generates content tagged with SAG type
|
||
- Publisher translates to WordPress: `cluster_hub` → create as `page` with hub template
|
||
- Future Shopify publisher: `cluster_hub` → create as Shopify `page` with equivalent template
|
||
|
||
---
|
||
|
||
## 13. Taxonomy Creation Flow
|
||
|
||
### 13.1 From Blueprint to WordPress
|
||
|
||
When a blueprint is confirmed, IGNY8 creates the defined taxonomies on WordPress via the plugin.
|
||
|
||
```
|
||
IGNY8 App WordPress Plugin
|
||
────────── ────────────────
|
||
1. Blueprint confirmed
|
||
2. Generate taxonomy payload ──────────> 3. Receive creation request
|
||
4. Register custom taxonomies
|
||
5. Create terms within each
|
||
6. Assign to post types
|
||
7. Update blueprint: created <────────── 7. Report success + term IDs
|
||
```
|
||
|
||
### 13.2 Handling Existing Taxonomies (Case 1)
|
||
|
||
For existing sites, some taxonomies may already exist:
|
||
|
||
| Situation | Action |
|
||
|-----------|--------|
|
||
| **Exact match** — taxonomy exists with same slug | Skip creation, map existing terms |
|
||
| **Similar match** — taxonomy exists with similar name | Present to user: "Is 'Product Category' the same as 'Device Type'?" |
|
||
| **No match** | Create new taxonomy |
|
||
| **Existing terms** | Merge — add new terms, map existing terms to blueprint values |
|
||
|
||
### 13.3 Product Attribute Enrichment
|
||
|
||
For Case 1 products lacking attributes:
|
||
1. AI reads product title + description
|
||
2. Identifies attribute values per product
|
||
3. Generates bulk assignments
|
||
4. User reviews → saves
|
||
|
||
---
|
||
|
||
## 14. Integration with IGNY8 Pipeline
|
||
|
||
### 14.1 Current vs SAG-Enhanced Pipeline
|
||
|
||
| Stage | Current | SAG-Enhanced |
|
||
|-------|---------|-------------|
|
||
| **Entry** | User adds keywords | Sector selection → attributes → clusters → keywords auto-generated |
|
||
| **Clustering** | AI groups keywords by similarity | Clusters pre-defined by attribute intersections; keywords map to them |
|
||
| **Ideas** | Generic ideas per cluster | Type-specific ideas (hub brief vs blog brief vs comparison brief) with correct Structure and Type fields |
|
||
| **Tasks** | All tasks same type | Tasks carry cluster type, content structure, and blueprint context |
|
||
| **Content** | Same prompts for everything | Type-specific prompts selected by Structure and Type |
|
||
| **Images** | Generic image generation | Image style matches content type (hub hero vs blog illustration vs product photo) |
|
||
| **Review** | Manual review | Review shows blueprint context — what cluster, what links to |
|
||
| **Publish** | Publish as post | Publish to correct post type, with correct taxonomies, correct template |
|
||
| **Post-Publish** | Nothing | Linker creates SAG-compliant internal links |
|
||
|
||
### 14.2 SAG-Enhanced Automation Pipeline
|
||
|
||
```
|
||
Stage 0: Blueprint Check
|
||
→ Verify active blueprint exists
|
||
→ Load unfulfilled content needs
|
||
|
||
Stage 1: Keyword Processing
|
||
→ Map any new keywords to existing clusters
|
||
→ Flag keywords that don't fit (potential new cluster)
|
||
|
||
Stage 2: Idea Generation (blueprint-guided)
|
||
→ Generate ideas per unfulfilled blueprint content needs
|
||
→ Each idea has correct Sector, Structure, Type, Cluster
|
||
|
||
Stage 3: Task Creation
|
||
→ Tasks carry blueprint context for content generation
|
||
|
||
Stage 4: Content Generation (type-specific)
|
||
→ Select prompt by Structure + Type
|
||
→ Include cluster context in prompt
|
||
|
||
Stage 5: Image Generation
|
||
→ Match image style to content type
|
||
|
||
Stage 6: Taxonomy Assignment
|
||
→ Auto-assign to correct custom taxonomies from blueprint
|
||
|
||
Stage 7: Review Queue
|
||
→ Blueprint context visible in review
|
||
→ Pre-computed internal links ready
|
||
```
|
||
|
||
### 14.3 Blueprint Health Monitoring
|
||
|
||
Background process that maintains blueprint integrity:
|
||
|
||
**Weekly health check:**
|
||
- Content completeness per cluster (hub exists? blogs published?)
|
||
- Internal link coverage
|
||
- Unassigned products/pages
|
||
- Taxonomy terms without content
|
||
- Overall SAG Health Score (0-100)
|
||
|
||
**Evolution triggers:**
|
||
- New products added to site
|
||
- New keywords don't fit existing clusters
|
||
- User adds new sector
|
||
- Manual user trigger
|
||
|
||
---
|
||
|
||
## 15. AI Prompt Architecture
|
||
|
||
### 15.1 Prompt Chain for Blueprint Generation
|
||
|
||
| Step | Prompt | Input | Output |
|
||
|------|--------|-------|--------|
|
||
| 1 | **Attribute Discovery** | Industry, sector(s), sector template (if exists) | Validated attribute framework |
|
||
| 2a | **Attribute Extraction** (Case 1) | Attributes + raw site data | Populated attributes from real data |
|
||
| 2b | **Attribute Population** (Case 2) | Attributes + user business inputs | Populated attributes from user data |
|
||
| 3 | **Cluster Formation** | Populated attributes | Clusters with types and intersections |
|
||
| 4 | **Keyword Generation** | Clusters + attribute values | Auto-generated keywords per cluster |
|
||
| 5 | **Content Planning** | Clusters + keywords + existing content (Case 1) | Content ideas with Structure and Type |
|
||
| 6 | **Blueprint Assembly** | All above | Complete SAG Blueprint JSON |
|
||
|
||
### 15.2 Content Generation Prompts (Enhanced)
|
||
|
||
Existing Thinker module prompts get SAG context variables:
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `{cluster_name}` | Cluster this content belongs to |
|
||
| `{cluster_type}` | Type classification |
|
||
| `{cluster_hub_title}` | Hub page title (for internal link reference) |
|
||
| `{cluster_hub_url}` | Hub page URL |
|
||
| `{attribute_terms}` | Attribute values this content should reference |
|
||
| `{cluster_products}` | Products in this cluster |
|
||
| `{related_blogs}` | Other blog posts in this cluster |
|
||
| `{content_type}` | SAG content type (hub, blog, product, term page) |
|
||
| `{content_structure}` | Structure (comparison, how to, review, etc.) |
|
||
|
||
---
|
||
|
||
## 16. Data Models & Schema
|
||
|
||
### 16.1 New Models
|
||
|
||
**SAGBlueprint**
|
||
```
|
||
- id (UUID)
|
||
- site_id (FK → Site)
|
||
- account_id (FK → Account)
|
||
- version (Integer)
|
||
- status (Enum: draft, active, evolving, archived)
|
||
- attributes (JSON) — full attribute framework with populated values
|
||
- clusters (JSON) — cluster definitions
|
||
- taxonomy_plan (JSON) — taxonomies to create
|
||
- execution_priority (JSON)
|
||
- sag_health_score (Float, 0-100)
|
||
- created_at, confirmed_at, created_by
|
||
```
|
||
|
||
**SAGAttribute**
|
||
```
|
||
- id (UUID)
|
||
- blueprint_id (FK → SAGBlueprint)
|
||
- name (String)
|
||
- slug (String)
|
||
- level (Enum: primary, secondary, tertiary)
|
||
- values (JSON array of {name, slug} objects)
|
||
- wp_taxonomy_slug (String, nullable) — set after taxonomy created on WordPress
|
||
- created_at
|
||
```
|
||
|
||
**SAGCluster**
|
||
```
|
||
- id (UUID)
|
||
- blueprint_id (FK → SAGBlueprint)
|
||
- site_id (FK → Site)
|
||
- name (String)
|
||
- cluster_type (Enum: product_category, condition_problem, feature, brand, informational, comparison)
|
||
- attribute_intersection (JSON) — which attribute values form this cluster
|
||
- auto_generated_keywords (JSON array)
|
||
- status (Enum: planned, partial, complete)
|
||
- content_count (Integer, computed)
|
||
- link_coverage_score (Float, 0-100)
|
||
- created_at
|
||
```
|
||
|
||
### 16.2 Modified Existing Models
|
||
|
||
All additions are nullable for backward compatibility:
|
||
|
||
**Cluster model:** Add `sag_cluster_id` (FK → SAGCluster), `cluster_type`
|
||
|
||
**Tasks model:** Add `sag_cluster_id`, `blueprint_context` (JSON)
|
||
|
||
**Content model:** Add `sag_cluster_id`
|
||
|
||
**ContentIdea model:** Add `sag_cluster_id`, `idea_source` (Enum: keyword_clustering, sag_blueprint, gap_analysis)
|
||
|
||
**Site model:** Add `sag_blueprint_id` (FK → SAGBlueprint, nullable) — active blueprint for site
|
||
|
||
### 16.3 Sector Attribute Framework Storage
|
||
|
||
New model or configuration store for sector-level attribute templates:
|
||
|
||
**SectorAttributeTemplate**
|
||
```
|
||
- id (UUID)
|
||
- industry (String)
|
||
- sector (String)
|
||
- site_type (Enum: e_commerce, services, saas, content, local_business, brand)
|
||
- attribute_framework (JSON) — template attributes with suggested values
|
||
- keyword_templates (JSON) — keyword generation templates per cluster type
|
||
- created_at, updated_at
|
||
- source (Enum: manual, ai_generated, user_contributed)
|
||
```
|
||
|
||
This is the NEW data layer that does not currently exist and must be built.
|
||
|
||
---
|
||
|
||
## 17. Implementation Phases
|
||
|
||
### Phase 1: Data Foundation (Weeks 1-3)
|
||
|
||
**Build the new data layer:**
|
||
- Create SAGBlueprint, SAGAttribute, SAGCluster models
|
||
- Create SectorAttributeTemplate model
|
||
- Blueprint CRUD API endpoints
|
||
- Add nullable SAG fields to existing Cluster, Tasks, Content, ContentIdea models
|
||
- Basic blueprint viewer in Site Settings (read-only)
|
||
|
||
### Phase 2: Sector Attribute Templates (Weeks 4-6)
|
||
|
||
**Build attribute intelligence:**
|
||
- Manually create attribute templates for top 5-8 sectors with highest user base
|
||
- AI-assisted template generation for remaining sectors
|
||
- Template loading, merging (multi-sector), and validation logic
|
||
- API: given industry + sectors → return attribute framework
|
||
|
||
### Phase 3: Cluster Formation & Keyword Generation (Weeks 7-9)
|
||
|
||
**Core SAG intelligence:**
|
||
- AI prompt for forming clusters from attribute intersections
|
||
- Cluster type classification logic
|
||
- Keyword auto-generation engine (templates per sector type)
|
||
- Keyword variant generation producing 300-500+ keywords per site
|
||
- Blueprint assembly from attributes → clusters → keywords
|
||
|
||
### Phase 4: Case 2 — Setup Wizard (Weeks 10-12)
|
||
|
||
**New site flow:**
|
||
- Add Site Structure step to wizard (Step 3)
|
||
- Attribute review UI
|
||
- Business details input forms (per site type)
|
||
- Blueprint preview UI
|
||
- Quick mode vs detailed mode
|
||
- Blueprint confirmation and storage
|
||
|
||
### Phase 5: Blueprint-Aware Content Pipeline (Weeks 13-15)
|
||
|
||
**Enhance existing pipeline:**
|
||
- Idea generation from blueprint (correct Sector, Structure, Type, Cluster)
|
||
- Task creation with blueprint context
|
||
- Type-specific prompt selection in Writer
|
||
- Auto taxonomy assignment on content creation
|
||
- Blueprint execution priority drives automation queue
|
||
|
||
### Phase 6: Taxonomy Creation (Weeks 16-17)
|
||
|
||
**WordPress integration:**
|
||
- Taxonomy creation payload generator
|
||
- Plugin endpoint to create taxonomies
|
||
- Existing taxonomy detection and mapping (Case 1)
|
||
- Taxonomy sync status tracking
|
||
|
||
### Phase 7: Case 1 — Existing Site Analysis (Weeks 18-21)
|
||
|
||
**Existing site intelligence:**
|
||
- Plugin site analysis endpoints (products, categories, taxonomies, content)
|
||
- AI attribute extraction from unstructured site data
|
||
- Gap analysis engine
|
||
- User confirmation UI for discovered attributes and proposed structure
|
||
- Product auto-tagging
|
||
|
||
### Phase 8: Health Monitoring & Polish (Weeks 22-24)
|
||
|
||
**Ongoing maintenance:**
|
||
- SAG Health Score calculation
|
||
- Weekly health check automation
|
||
- Blueprint evolution triggers
|
||
- Dashboard health widget
|
||
- End-to-end testing both cases
|
||
- Documentation
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
The SAG implementation transforms IGNY8 from a keyword-dependent content tool into a structure-first site architecture engine. The key shifts:
|
||
|
||
1. **Attributes replace keywords as the structural foundation.** Keywords emerge from attribute intersections; they don't define structure.
|
||
|
||
2. **Clusters are attribute intersections, not keyword groups.** A cluster exists because Target Area=Foot and Relief Focus=Neuropathy intersect meaningfully — not because someone added "foot massager neuropathy" to their keyword list.
|
||
|
||
3. **The system operates without manual keyword input.** 300-500+ keywords auto-generate from attribute value combinations. Users can add more, but the base is self-sufficient.
|
||
|
||
4. **Content types match cluster types.** Hub pages, blog posts, product pages, attribute term pages, category pages — each gets the right Structure and Type based on its role in the SAG architecture.
|
||
|
||
5. **Platform-agnostic concepts, platform-specific publishing.** The same SAG architecture works across WordPress, Shopify, and custom sites — only the publishing layer changes.
|
||
|
||
6. **Sector attribute templates are a completely new data layer.** Current IGNY8 sectors carry zero structural intelligence. Building this layer is the foundational work that everything else depends on.
|
||
|
||
---
|
||
|
||
*Cross-references:*
|
||
- *SAG-Master-Document.md — Pure SAG methodology and clustering rules*
|
||
- *SAG-Interlinking-Specification.md — Linker module specification (Document 3)*
|
||
- *SAG-Backlink-Campaign-Specification.md — External backlink campaigns (Document 4)*
|