igny8/v2/V2-Execution-Docs/01D-setup-wizard-case2-new-site.md

IGNY8 Phase 1: Setup Wizard — Case 2 (New Site)

Document 01D: Build Specification

Status: Draft Version: 1.0 Date: 2026-03-23 Phase: Phase 1 — Foundation Scope: New site workflow with enhanced Site Structure step

---

1. CURRENT STATE

Existing Wizard Flow

The IGNY8 setup wizard currently operates in 5 steps:

1. Welcome — Introduction, mode selection (Quick vs. Detailed)
2. Add Site — Capture site metadata (name, URL, industry, sectors up to 5)
3. Connect WordPress — Plugin installation and authentication
4. Keywords — Optional keyword input/review
5. Complete — Summary and "Start generating" CTA

Existing Models & Services

• SAGBlueprint model exists (01A reference) — stores blueprint data with status field (draft, active)
• SAGAttribute model exists (01A reference) — stores attribute definitions linked to blueprint
• template_service exists (01B reference) — provides get_or_generate_template() for sector-based attribute frameworks
• cluster_formation logic exists (01C reference) — groups keywords and content into hierarchical clusters
• keyword_generation exists (01C reference) — auto-generates keywords from attributes

Limitations of Current Wizard

• No structured attribute review — site structure is invisible to user during setup
• Generic blueprints — relies entirely on template defaults, no business data input
• Keywords are separate — no preview of how attributes map to clusters/keywords
• No before/after — users cannot see generated site structure until after wizard completes
• No quick vs. detailed — all paths treat onboarding the same

---

2. WHAT TO BUILD

Overview

This document specifies an enhanced setup wizard that inserts a new Step 3: Site Structure between "Add Site" and "Connect WordPress". This step allows users to:

1. Review AI-generated attributes from their industry/sectors
2. Input business details (products, services, brands, locations, problems)
3. See AI populate attributes from their business context
4. Preview the resulting blueprint (clusters, keywords, content plan)
5. Confirm to activate the blueprint or refine further

This creates a transparent, user-directed blueprint building process while maintaining a quick mode for users who want full automation.

Enhanced Wizard Flow

Step 1: Welcome
  └─ Select mode: Quick Mode or Detailed Mode

Step 2: Add Site (EXISTING — no changes)
  └─ Input: site name, URL, industry, sectors (up to 5)
  └─ Output: site_id created

Step 3: Site Structure (NEW — core of this document)
  ├─ 3a: Generate Attribute Framework
  │  └─ AI generates attributes from industry + sectors using template_service
  │  └─ Output: attribute list with suggested values
  │
  ├─ 3b: Attribute Review (Detailed Mode only, skipped in Quick Mode)
  │  └─ UI: Primary/Secondary/Tertiary attribute panels
  │  └─ Actions: toggle, edit values, reorder, add custom
  │
  ├─ 3c: Business Details Input (Detailed Mode only, optional in Quick Mode)
  │  └─ Structured form: Products, Services, Brands, Locations, Conditions/Problems
  │
  ├─ 3d: AI Attribute Population (Detailed Mode only)
  │  └─ AI populates attributes from business data
  │  └─ Output: populated_attributes with site-specific values
  │
  ├─ 3e: Blueprint Preview
  │  └─ Tree view: clusters, keywords, content plan visualization
  │  └─ Read-only preview — shows what blueprint will contain
  │
  └─ 3f: Confirm & Create Blueprint
     └─ User confirms → SAGBlueprint created (status: draft → active)

Step 4: Connect WordPress (EXISTING — ENHANCED)
  └─ Plugin auto-creates taxonomies from confirmed blueprint attributes
  └─ Syncs cluster hierarchy into WordPress taxonomy structure

Step 5: Keywords (NOW OPTIONAL)
  └─ Can be skipped if auto-generated keywords sufficient
  └─ Can be used to supplement or refine if desired

Step 6: Complete
  └─ Blueprint summary, content plan overview
  └─ "Start generating" CTA directs to content pipeline (01E)

Mode Selection: Quick vs. Detailed

Quick Mode

Tagline: "Let IGNY8 build your site structure automatically"

Behavior:

• Skip Step 3b (attribute review)
• Skip Step 3c (business details input)
• Skip Step 3d (attribute population)
• Use sector template defaults
• Auto-generate blueprint immediately after site creation
• User can refine in Site Settings later

Flow:

Step 2 → Step 3a (generate framework) →
Step 3e (preview) → Step 3f (confirm) →
Step 4 (Connect WordPress) → Step 5 (Keywords — optional) → Step 6 (Complete)

Ideal for: Established niches, straightforward industries, users confident in IGNY8's templates

Detailed Mode

Tagline: "Customize your site structure with your business data"

Behavior:

• Full Step 3b (attribute review with edit capabilities)
• Full Step 3c (structured business details input)
• Step 3d (AI population from business context)
• Generate tailored, business-specific blueprint
• More accurate for unique or niche content

Flow:

Step 2 → Step 3a → Step 3b → Step 3c →
Step 3d (AI populate) → Step 3e → Step 3f →
Step 4 → Step 5 → Step 6

Ideal for: Niche markets, specialized services, users with specific branding/positioning

---

3. DATA MODELS / APIs

3.1 Enhanced SAGBlueprint Model

Location: Reference 01A (Blueprint Definition)

# Fields to emphasize for this wizard:
class SAGBlueprint(models.Model):
    site_id = models.ForeignKey(Site)
    status = models.CharField(
        choices=['draft', 'active', 'archived'],
        default='draft'
    )

    # Wizard-generated data
    attributes = models.ManyToManyField(SAGAttribute)
    populated_attributes = models.JSONField(null=True)  # Stores business-enriched attributes

    # Cluster & keyword refs
    clusters = models.ManyToManyField(SAGCluster)
    keyword_count = models.IntegerField(default=0)
    content_plan_count = models.IntegerField(default=0)

    # Audit
    created_via = models.CharField(default='wizard')  # 'wizard' or 'import' or 'manual'
    created_at = models.DateTimeField(auto_now_add=True)
    confirmed_at = models.DateTimeField(null=True)  # Set when user confirms in Step 3f

    # WordPress sync
    wordpress_synced = models.BooleanField(default=False)
    wordpress_synced_at = models.DateTimeField(null=True)

3.2 Enhanced SAGAttribute Model

Location: Reference 01A (Attribute Definition)

class SAGAttribute(models.Model):
    blueprint = models.ForeignKey(SAGBlueprint)
    name = models.CharField()  # e.g., "Target Area"
    description = models.TextField()

    # Attribute classification
    level = models.CharField(
        choices=['primary', 'secondary', 'tertiary', 'custom'],
        default='secondary'
    )

    # Values and state
    values = models.JSONField(default=list)  # ["Neck", "Foot", "Face", ...]
    suggested_values = models.JSONField(default=list)  # From template
    enabled = models.BooleanField(default=True)  # Toggle from Step 3b

    # From Step 3d population
    populated_from_business_data = models.BooleanField(default=False)
    business_sources = models.JSONField(default=dict)  # {product_names, service_types, ...}

    # Status tracking
    completeness = models.CharField(
        choices=['ready', 'thin', 'empty'],
        default='empty'
    )
    # ready: all primary values present, sufficient secondary
    # thin: some primary values, minimal secondary
    # empty: no user-provided values (template defaults only)

    order = models.IntegerField(default=0)  # For Step 3b reordering

3.3 Wizard API Endpoints

Endpoint 1: POST /api/v1/sag/wizard/generate-attributes/

Called by: Step 3a Purpose: Generate attribute framework from industry + sectors using template_service

Request:

{
  "industry": "Health & Wellness",
  "sectors": ["Massage Devices", "Pain Relief"],
  "site_type": "ecommerce"
}

Response (200 OK):

{
  "attributes": [
    {
      "name": "Target Area",
      "level": "primary",
      "suggested_values": ["Neck", "Foot", "Face", "Back", "Shoulder"],
      "description": "Body area targeted by massage devices"
    },
    {
      "name": "Device Type",
      "level": "primary",
      "suggested_values": ["Shiatsu", "EMS", "Heated", "Percussion", "TENS"],
      "description": "Technology or method of the device"
    },
    {
      "name": "Relief Focus",
      "level": "secondary",
      "suggested_values": ["Neuropathy", "Plantar Fasciitis", "Circulation", "Muscle Recovery"],
      "description": "Health condition or benefit targeted"
    },
    {
      "name": "Therapy Method",
      "level": "secondary",
      "suggested_values": ["Deep Tissue", "TENS", "NMES", "Heat Therapy"],
      "description": "Therapeutic approach"
    },
    {
      "name": "Brand",
      "level": "tertiary",
      "suggested_values": [],
      "description": "Your brand or partner brands"
    },
    {
      "name": "Features",
      "level": "tertiary",
      "suggested_values": ["Cordless", "Portable", "Waterproof", "Battery Life"],
      "description": "Key features or specs"
    }
  ],
  "total_attributes": 6
}

Logic:

1. Call template_service.get_or_generate_template(industry, sectors)
2. Return template's attribute definitions
3. Organize by level (primary → secondary → tertiary)
4. Include suggested_values from template
5. Exclude attributes with zero relevance (determined by sector rules)

---

Endpoint 2: POST /api/v1/sag/wizard/populate-attributes/

Called by: Step 3d (Detailed Mode only) Purpose: Use AI to populate attributes from business data context

Request:

{
  "attributes": [
    {
      "name": "Target Area",
      "level": "primary",
      "suggested_values": ["Neck", "Foot", "Face", "Back", "Shoulder"],
      "current_values": ["Neck", "Back"]
    },
    {
      "name": "Device Type",
      "level": "primary",
      "suggested_values": ["Shiatsu", "EMS", "Heated", "Percussion", "TENS"],
      "current_values": []
    }
  ],
  "business_data": {
    "products": "Theragun Elite, Neck Massager Pro, Percussion device for muscle recovery",
    "services": "Custom therapy plans, muscle recovery consulting",
    "conditions": "Neuropathy, chronic pain, muscle tension, recovery from sports injury",
    "locations": "US, Canada",
    "brands": "TheraActive, HealFlow"
  }
}

Response (200 OK):

{
  "populated_attributes": [
    {
      "name": "Target Area",
      "level": "primary",
      "values": ["Neck", "Back"],
      "populated_from_business_data": true,
      "business_sources": ["products mention Neck Massager", "products mention muscle tension"],
      "completeness": "ready"
    },
    {
      "name": "Device Type",
      "level": "primary",
      "values": ["Percussion", "Heated"],
      "populated_from_business_data": true,
      "business_sources": ["Theragun Elite → Percussion", "Neck Massager Pro → Heated"],
      "completeness": "ready"
    },
    {
      "name": "Relief Focus",
      "level": "secondary",
      "values": ["Neuropathy", "Chronic Pain", "Muscle Recovery", "Sports Injury Recovery"],
      "populated_from_business_data": true,
      "business_sources": ["conditions: Neuropathy, chronic pain, muscle recovery"],
      "completeness": "ready"
    },
    {
      "name": "Brand",
      "level": "tertiary",
      "values": ["TheraActive", "HealFlow"],
      "populated_from_business_data": true,
      "business_sources": ["brands input"],
      "completeness": "ready"
    }
  ],
  "populated_count": 4,
  "completeness_summary": {
    "ready": 4,
    "thin": 0,
    "empty": 0
  }
}

Logic: Handled by AI function (see Section 3.4 below)

---

Endpoint 3: POST /api/v1/sag/wizard/generate-blueprint/

Called by: Step 3f (after user confirms attributes) Purpose: Create SAGBlueprint, call cluster formation & keyword generation

Request:

{
  "site_id": 123,
  "populated_attributes": [
    {
      "name": "Target Area",
      "values": ["Neck", "Back"],
      "level": "primary"
    }
  ],
  "mode": "detailed"
}

Response (201 Created):

{
  "blueprint_id": 456,
  "status": "draft",
  "clusters": [
    {
      "cluster_id": 1001,
      "name": "Neck Massage Devices",
      "type": "topic_hub",
      "keyword_count": 24,
      "content_plan_count": 8
    },
    {
      "cluster_id": 1002,
      "name": "Back Pain Relief",
      "type": "topic_hub",
      "keyword_count": 18,
      "content_plan_count": 6
    }
  ],
  "keyword_count": 42,
  "content_plan_count": 14,
  "created_at": "2026-03-23T10:15:00Z"
}

Logic:

1. Create SAGBlueprint record with status='draft'
2. Store attributes in blueprint.attributes and blueprint.populated_attributes
3. Call cluster_formation.form_clusters(blueprint_id, attributes) (01C)
4. Call keyword_generation.generate(blueprint_id, clusters) (01C)
5. Store cluster_ids, keyword_count, content_plan_count
6. Return blueprint_id and summary data for Step 3e preview

---

Endpoint 4: POST /api/v1/sag/wizard/confirm-blueprint/

Called by: Step 3f (user clicks "Approve & Build") Purpose: Activate blueprint (draft → active) and lock for WordPress sync

Request:

{
  "blueprint_id": 456
}

Response (200 OK):

{
  "success": true,
  "blueprint_id": 456,
  "status": "active",
  "confirmed_at": "2026-03-23T10:16:00Z"
}

Logic:

1. Load blueprint record
2. Verify status is 'draft'
3. Set status = 'active'
4. Set confirmed_at = now
5. Return success response
6. Trigger webhook or signal to notify Step 4 (WordPress sync) that blueprint is ready

---

3.4 AI Function: PopulateAttributes

Location: sag/ai_functions/attribute_population.py Called by: Endpoint 2 (Step 3d) Purpose: Use LLM to populate attributes with site-specific values from business data

Input:

{
    "attributes": [
        {
            "name": "Target Area",
            "level": "primary",
            "suggested_values": ["Neck", "Foot", "Face", "Back", "Shoulder"],
            "current_values": ["Neck", "Back"]
        }
    ],
    "business_data": {
        "products": "...",
        "services": "...",
        "conditions": "...",
        "locations": "...",
        "brands": "..."
    }
}

Output:

{
    "populated_attributes": [
        {
            "name": "Target Area",
            "values": ["Neck", "Back"],
            "populated_from_business_data": True,
            "business_sources": {
                "products": ["Neck Massager Pro"],
                "conditions": ["neck tension"]
            },
            "completeness": "ready"
        }
    ]
}

Algorithm:

1. Parse Business Data

   • Split comma-separated or line-break-separated inputs
   • Extract entities (product names, service types, conditions, brands, locations)
   • Normalize text (lowercase, strip whitespace)

2. Map to Suggested Values

   • For each attribute, attempt fuzzy matching of business data items to suggested_values
   • If "Theragun Elite" (product) contains "percussion" → map to "Percussion" device type
   • If condition is "neuropathy" → keep "Neuropathy" in Relief Focus
   • Build mapping: suggested_value → source_items

3. Identify New Values

   • For values in business_data NOT matching suggested_values
   • Example: user brands "MyBrand" not in suggested values → ADD as new value
   • Set new values as "user-defined" or "inferred"

4. Apply Pruning Rules

   • Demote attributes with only 1 value from primary → secondary
   • Remove empty attributes if no business data provided
   • Consolidate similar values (e.g., "heat" and "heating" → "Heat Therapy")

5. Assess Completeness

   • Ready: Primary attribute has 2+ values OR secondary has 3+ values
   • Thin: Primary has 1 value OR secondary has 1–2 values
   • Empty: No user-provided or inferred values, only template defaults

6. Return Populated Attributes

   • Include completeness status per attribute
   • Track business_sources for transparency (show user where values came from)

LLM Prompt (system):

You are an expert content strategist analyzing business data to populate site structure attributes.

Given:
- An attribute definition (name, suggested_values, level)
- Business data (products, services, conditions, brands, locations)

Your task:
1. Map business data items to the most relevant suggested_values
2. Identify any new values not in suggested_values (brand names, unique conditions, etc.)
3. Provide reasoning: which business data item → which attribute value
4. Flag completeness: is this attribute "ready" (sufficient values), "thin" (minimal), or "empty"?

Output JSON with:
- mapped_values: [list of relevant suggested_values + any new values]
- sources: {suggested_value: [business_data_items that led to it]}
- completeness: 'ready' | 'thin' | 'empty'
- reasoning: brief explanation

Be conservative: only map if connection is clear. Do not invent values not supported by business data.

---

4. IMPLEMENTATION STEPS

Phase 1: Backend API & Models

Step 1.1: Enhance Models

• Update SAGBlueprint model with new fields (confirmed_at, created_via, wordpress_synced, etc.)
• Update SAGAttribute model with new fields (level, populated_from_business_data, completeness, etc.)
• Create database migrations
• Run migrations in dev environment
• Test model creation and field defaults

Deliverable: Updated models in 01A, migrations applied

---

Step 1.2: Implement PopulateAttributes AI Function

• Create sag/ai_functions/attribute_population.py
• Implement business data parsing (products, services, conditions, brands, locations)
• Implement fuzzy matching to suggested_values
• Implement completeness assessment logic
• Write unit tests:
  • Test parsing of comma-separated input
  • Test fuzzy matching (e.g., "percussion" → "Percussion Device Type")
  • Test new value identification
  • Test completeness scoring
• Integration test: call function with sample business data, verify output structure

Deliverable: attribute_population.py with comprehensive test coverage

---

Step 1.3: Implement Wizard API Endpoints

• POST /api/v1/sag/wizard/generate-attributes/

  • Call template_service.get_or_generate_template()
  • Filter attributes by relevance (remove zero-relevance attrs)
  • Organize output by level
  • Unit test: verify output matches spec
  • Integration test: test with different industry/sector combinations

• POST /api/v1/sag/wizard/populate-attributes/

  • Call attribute_population.py function
  • Validate input structure
  • Return populated_attributes with sources
  • Unit test: verify AI function is called correctly
  • Integration test: test with sample business data

• POST /api/v1/sag/wizard/generate-blueprint/

  • Create SAGBlueprint record
  • Call cluster_formation.form_clusters() (01C)
  • Call keyword_generation.generate() (01C)
  • Store results in blueprint
  • Unit test: verify blueprint creation and cluster formation
  • Integration test: verify end-to-end blueprint generation

• POST /api/v1/sag/wizard/confirm-blueprint/

  • Update blueprint status to 'active'
  • Set confirmed_at timestamp
  • Emit signal/webhook for WordPress sync (Step 4)
  • Unit test: verify status transition
  • Integration test: verify webhook emission

Deliverable: All four endpoints fully functional with tests

---

Step 1.4: Integrate with Existing Services

• Verify template_service integration in generate-attributes endpoint
• Verify cluster_formation integration in generate-blueprint endpoint
• Verify keyword_generation integration in generate-blueprint endpoint
• Test cross-service data flow:
  • Generate attributes → populate attributes → generate blueprint
• Documentation: add to API docs (swagger/openapi)

Deliverable: Integrated, end-to-end API flow verified

---

Phase 2: Frontend Components (React)

Step 2.1: Implement WizardStep3Container

• Create frontend/src/components/wizard/WizardStep3Container.jsx
• Manage state for all sub-steps (3a–3f):
  • currentSubstep (enum: 'generate', 'review', 'business', 'populate', 'preview', 'confirm')
  • attributes (from API)
  • businessData (user input)
  • populatedAttributes (from AI)
  • blueprintData (preview)
  • mode ('quick' or 'detailed')
• Implement sub-step navigation (next, prev, skip logic)
  • Quick mode: skip to step 3e
  • Detailed mode: show all steps
• Handle loading states and error messages
• Unit test: state transitions, sub-step navigation
• Integration test: full flow through all sub-steps

Deliverable: WizardStep3Container with all sub-step logic

---

Step 2.2: Implement AttributeReviewPanel (Step 3b)

• Create frontend/src/components/wizard/AttributeReviewPanel.jsx
• Render attributes grouped by level:
  • Primary Attributes section
  • Secondary Attributes section
  • Tertiary Attributes section
  • + Add Custom Attribute button
• For each attribute:
  • Toggle checkbox (enable/disable)
  • Value pills with edit/delete (e.g., "[Neck] [Back] [+ Add]")
  • Inline add-value input
  • Drag-to-reorder
• Implement value editing:
  • Click value → open edit modal
  • Inline validation (no duplicates, max length)
  • Save/cancel
• Implement custom attribute addition:
  • Form: attribute name, level, suggested values (comma-separated)
  • Add to local state
  • Persist to backend on confirm (Step 3f)
• Styling: match IGNY8 design system
• Unit test: toggle, edit, add, reorder actions
• Component test: render with different attribute sets

Deliverable: Fully functional AttributeReviewPanel component

---

Step 2.3: Implement BusinessDetailsForm (Step 3c)

• Create frontend/src/components/wizard/BusinessDetailsForm.jsx
• Fields:
  • Products — textarea, accepts comma-separated or line-break list
  • Services — textarea, same format
  • Brands — textarea, comma-separated
  • Locations — multi-select (country dropdown + add custom)
  • Conditions/Problems — textarea, comma-separated
• Implement text parsing on input change:
  • Extract and normalize items
  • Show "x items detected" feedback
  • Allow user to add/remove items in live list
• Implement validation:
  • At least one field required
  • Max 50 items per field
  • No special characters in brands (basic sanitization)
• State management: sync with WizardStep3Container
• Styling: clean, form-like UI
• Unit test: parsing, validation, state updates
• Component test: render form, submit data

Deliverable: Fully functional BusinessDetailsForm component

---

Step 2.4: Implement BlueprintPreviewPanel (Step 3e)

• Create frontend/src/components/wizard/BlueprintPreviewPanel.jsx
• Render tree view of clusters:
  • Cluster name (e.g., "Neck Massage Devices")
  • Type badge (e.g., "Topic Hub")
  • Keyword count (e.g., "24 keywords")
  • Content plan count (e.g., "8 pieces")
  • Expand/collapse per cluster
  • Show supporting content types when expanded (guides, reviews, comparisons)
• Summary row:
  • Total clusters
  • Total keywords
  • Total content plan items
• Action buttons:
  • "Approve & Build" (calls confirm-blueprint endpoint, advances to Step 4)
  • "Adjust Attributes" (back to Step 3b or 3c)
  • Disabled state if no clusters generated (error handling)
• Loading state: skeleton tree while generating
• Error state: message if blueprint generation failed with retry button
• Styling: clean tree UI, color-coded by cluster type
• Unit test: render clusters, expand/collapse, button clicks
• Component test: loading and error states

Deliverable: Fully functional BlueprintPreviewPanel component

---

Step 2.5: Implement QuickDetailedModeToggle (Step 1)

• Modify existing Welcome screen (Step 1) to include mode selection
• Create toggle/radio group:
  • Quick Mode card/radio
    • Icon (lightning bolt or similar)
    • Tagline: "Let IGNY8 build your site structure automatically"
    • Description: "Uses proven templates for your industry. Refine later if needed."
  • Detailed Mode card/radio
    • Icon (settings or pencil)
    • Tagline: "Customize your site structure with your business data"
    • Description: "Input your products, services, and business details. AI tailors the blueprint."
• Pass mode selection to WizardStep3Container
• Unit test: mode selection and passing to Step 3

Deliverable: Enhanced Step 1 with mode toggle

---

Step 2.6: Integration & Navigation

• Update wizard router to include Step 3:
  • /wizard/step-1 (Welcome + mode)
  • /wizard/step-2 (Add Site)
  • /wizard/step-3 (Site Structure) ← NEW
  • /wizard/step-4 (Connect WordPress)
  • /wizard/step-5 (Keywords)
  • /wizard/step-6 (Complete)
• Implement next/prev button logic:
  • Step 1 → Step 2 (always)
  • Step 2 → Step 3 (always)
  • Step 3:
    • Quick Mode: 3a → 3e → 3f → Step 4
    • Detailed Mode: 3a → 3b → 3c → 3d → 3e → 3f → Step 4
  • Step 4 → Step 5 (always)
  • Step 5 → Step 6 (always)
• Implement state persistence (Redux or context):
  • Save wizard state to localStorage or session
  • Allow user to resume if page refreshes
• Unit test: navigation logic for both modes
• E2E test: complete wizard flow (Quick and Detailed)

Deliverable: Fully integrated wizard navigation

---

Phase 3: WordPress Plugin Enhancement (Step 4 Integration)

Step 3.1: Auto-Create Taxonomies from Blueprint

• Update WordPress plugin to listen for blueprint.status = 'active' signal
• Implement taxonomy creation:
  • For each attribute → create WordPress taxonomy
  • Attribute name → taxonomy slug
  • Attribute values → taxonomy terms
  • Attribute level → taxonomy hierarchy (primary at root)
• Implement hierarchy:
  • Primary attributes → top-level taxonomies
  • Secondary attributes → nested within primary (if appropriate)
  • Tertiary attributes → custom fields or flat taxonomies
• Implement sync on future attribute changes:
  • If user edits attribute in Site Settings → sync to WordPress
  • If user adds new term → sync to WordPress
• Unit test: taxonomy creation, hierarchy
• Integration test: verify taxonomies appear in WordPress admin

Deliverable: Plugin auto-creates taxonomies on blueprint confirmation

---

Phase 4: Testing & QA

Step 4.1: Unit Tests

• Backend:
  • Test all API endpoints with valid/invalid inputs
  • Test PopulateAttributes AI function with various business data
  • Test model changes and migrations
• Frontend:
  • Test all component state changes
  • Test form validation
  • Test navigation logic
• Target: 80%+ code coverage

Deliverable: Comprehensive unit test suite

---

Step 4.2: Integration Tests

• Backend:
  • Test full wizard flow: generate → populate → blueprint → confirm
  • Test Quick Mode vs. Detailed Mode paths
  • Test cross-service calls (template_service, cluster_formation, keyword_generation)
• Frontend:
  • E2E: complete wizard in Quick Mode
  • E2E: complete wizard in Detailed Mode
  • E2E: edit attributes, input business data, review preview
• Cross-system:
  • Test blueprint confirmation triggers WordPress sync
  • Test WordPress taxonomies created correctly

Deliverable: Comprehensive integration test suite

---

Step 4.3: UAT (User Acceptance Testing)

• Prepare UAT test plan with scenarios:
  • Scenario 1: New massage device ecommerce site (Detailed Mode)
  • Scenario 2: Digital marketing agency (Quick Mode, then refine)
  • Scenario 3: Niche B2B service (Detailed Mode with custom attributes)
• Internal UAT: test with IGNY8 team
• Feedback collection: usability, clarity, completeness
• Bug fixes and iterations

Deliverable: UAT report, bug fixes applied

---

Phase 5: Documentation & Deployment

Step 5.1: Technical Documentation

• API documentation:
  • Add endpoints to swagger/openapi spec
  • Include request/response examples
  • Document error codes and handling
• Component documentation:
  • Storybook stories for React components
  • Props documentation
  • Usage examples
• Database schema documentation:
  • Updated ER diagrams
  • Migration notes
• AI function documentation:
  • Prompt engineering notes
  • Input/output specifications
  • Examples

Deliverable: Complete technical documentation

---

Step 5.2: User Documentation

• Wizard user guide:
  • Step-by-step screenshots
  • Mode comparison (Quick vs. Detailed)
  • Tips for each step
  • FAQ
• Video tutorials:
  • Quick Mode walkthrough (2–3 min)
  • Detailed Mode walkthrough (5–7 min)
  • Attribute editing and customization
• Blog post: "Introducing IGNY8's New Site Structure Wizard"
  • Benefits of the new workflow
  • When to use Quick vs. Detailed
  • Real-world examples

Deliverable: Complete user documentation + video tutorials

---

Step 5.3: Deployment

• Staging deployment:
  • Deploy backend API changes
  • Deploy frontend changes
  • Deploy WordPress plugin updates
  • Run full integration test suite in staging
  • Verify data migration (if any)
• Production deployment:
  • Prepare deployment plan (rollback strategy, rollout schedule)
  • Feature flag: keep wizard as opt-in initially
  • Monitor logs for errors
  • Support team briefing
• Post-deployment:
  • Monitor error rates and API latency
  • Collect early user feedback
  • Hotfix any critical issues

Deliverable: Successfully deployed to production with monitoring in place

---

5. ACCEPTANCE CRITERIA

Functional Criteria

5.1: Step 3a — Generate Attributes

• AC-3a-1: GET /api/v1/sag/wizard/generate-attributes/ returns attribute framework

  • Response includes 4–8 attributes (depending on industry/sectors)
  • Each attribute has name, level, suggested_values, description
  • Attributes are organized by level (primary → secondary → tertiary)
  • Suggested values are relevant to industry/sectors (validated by team)

• AC-3a-2: Attributes are called from template_service

  • Verified in code review: template_service.get_or_generate_template() is called
  • Template is selected based on industry + sectors
  • Zero-relevance attributes are filtered out

• AC-3a-3: UI displays loading state while generating

  • Spinner or skeleton appears while API call is in flight
  • User cannot interact with next button during loading
  • Error message shown if API fails

---

5.2: Step 3b — Attribute Review (Detailed Mode only)

• AC-3b-1: All attributes render with proper grouping

  • Primary, Secondary, Tertiary sections visible
  • Each attribute shows toggle, values, edit, + Add button
  • Custom attribute option visible at bottom

• AC-3b-2: User can toggle attributes on/off

  • Toggle changes enable/disable flag in local state
  • Disabled attributes are grayed out (visual feedback)
  • State persists during wizard (not lost on sub-step navigation)

• AC-3b-3: User can add/edit/delete values

  • Click value → inline edit modal or popover
  • Enter new value → validate for duplicates, max length
  • Click + Add → inline input field appears
  • Delete value → remove from list (with confirmation for primary)
  • Reorder values by drag-and-drop

• AC-3b-4: User can add custom attributes

  • Click "+ Add Custom Attribute" → form appears
  • Form fields: attribute name, level, suggested values
  • Form validation: name required, level selected, no duplicates with existing
  • Custom attribute added to local state
  • Persisted when user confirms Step 3f

• AC-3b-5: UI reflects completeness status (visual indicator)

  • Ready attributes show green checkmark or similar
  • Thin attributes show yellow warning
  • Empty attributes show red flag
  • Status updates as user adds/removes values

---

5.3: Step 3c — Business Details Input (Detailed Mode only)

• AC-3c-1: Form accepts all five fields

  • Products textarea accepts comma-separated or line-break input
  • Services textarea accepts same format
  • Brands textarea (comma-separated)
  • Locations dropdown + custom input
  • Conditions/Problems textarea

• AC-3c-2: Parsing works correctly

  • User enters "Theragun Elite, Neck Massager Pro" → system extracts ["Theragun Elite", "Neck Massager Pro"]
  • "Neuropathy\nChronic pain" → ["Neuropathy", "Chronic pain"]
  • Whitespace trimmed, duplicates removed

• AC-3c-3: Validation enforces requirements

  • At least one field must have content
  • Max 50 items per field enforced
  • Basic sanitization (no special characters in brands)
  • Error messages shown for violations

• AC-3c-4: Data persists in state

  • User moves to Step 3d, data is preserved
  • User goes back to Step 3c, data is restored

---

5.4: Step 3d — AI Attribute Population

• AC-3d-1: PopulateAttributes AI function is called

  • POST /api/v1/sag/wizard/populate-attributes/ invoked with attributes + business_data
  • Function receives correct input structure

• AC-3d-2: AI correctly maps business data to attributes

  • Example: user enters product "Theragun Elite" → system infers "Percussion" device type
  • Example: condition "neuropathy" → "Neuropathy" relief focus
  • Example: brand "TheraActive" → added to Brand attribute
  • Mapping is accurate (no false positives)

• AC-3d-3: New values are identified

  • Values in business data NOT in suggested_values are added as "user-defined"
  • Example: user brand "MyCustomBrand" added to Brand values
  • Example: unique condition not in template → added to Relief Focus

• AC-3d-4: Completeness is assessed correctly

  • Attribute with 2+ primary values → "ready"
  • Attribute with 1 primary value → "thin"
  • Attribute with 0 values → "empty"
  • Completeness summary returned to frontend

• AC-3d-5: Business sources are transparent

  • Response includes which business data item → which attribute value
  • Example: {Percussion: ["products: Theragun Elite"]}
  • UI can display source for user verification

• AC-3d-6: Loading and error states handled

  • Spinner while AI function processes (up to 30 sec)
  • Error message if API fails (with retry button)
  • Timeout handling if function takes >60 sec

---

5.5: Step 3e — Blueprint Preview

• AC-3e-1: Tree view renders correctly

  • Clusters grouped by category
  • Each cluster shows name, type badge, keyword count, content plan count
  • Expand/collapse functionality works
  • Visual hierarchy is clear

• AC-3e-2: Summary row shows totals

  • Total cluster count displayed
  • Total keyword count displayed
  • Total content plan count displayed
  • Numbers match backend data

• AC-3e-3: Action buttons present and functional

  • "Approve & Build" button calls confirm-blueprint endpoint
  • "Adjust Attributes" button navigates back to Step 3b (Detailed) or Step 3a (Quick)
  • Buttons disabled if no clusters or error state

• AC-3e-4: Error handling

  • If blueprint generation fails, user sees error message with retry
  • If clusters are empty, user sees message recommending attribute adjustment
  • User can go back to adjust without losing data

---

5.6: Step 3f — Confirm & Create Blueprint

• AC-3f-1: Confirm-blueprint endpoint creates SAGBlueprint

  • SAGBlueprint record created with status='draft'
  • Attributes linked to blueprint
  • populated_attributes stored as JSON
  • created_via='wizard' set

• AC-3f-2: Blueprint status transitions correctly

  • Before confirm: blueprint.status = 'draft'
  • After confirm: blueprint.status = 'active'
  • confirmed_at timestamp set
  • Status change triggers webhook/signal for WordPress sync

• AC-3f-3: User sees confirmation message

  • "Blueprint created successfully" message shown
  • "Next: Connect WordPress" CTA visible
  • Next button advances to Step 4

---

Integration Criteria

5.7: Quick Mode vs. Detailed Mode

• AC-5-1: Quick Mode skips Steps 3b–3d

  • User selects "Quick Mode" in Step 1
  • Step 2 → Step 3a (generate) → Step 3e (preview) → Step 3f (confirm) → Step 4
  • Steps 3b, 3c, 3d are not shown

• AC-5-2: Detailed Mode shows all steps

  • User selects "Detailed Mode" in Step 1
  • All steps 3a–3f are displayed in order
  • User can navigate freely between steps (prev/next)

• AC-5-3: Mode selection persists

  • Mode stored in session/Redux state
  • Navigation logic respects mode throughout wizard

---

5.8: WordPress Plugin Integration

• AC-5-4: Plugin listens for blueprint confirmation

  • Signal emitted when blueprint.status = 'active'
  • Plugin receives blueprint data (attributes, clusters)

• AC-5-5: Plugin auto-creates taxonomies

  • For each attribute → create WordPress taxonomy
  • Taxonomy name matches attribute name
  • Taxonomy terms created from attribute values
  • Hierarchy reflects attribute levels (primary/secondary)

• AC-5-6: Taxonomies appear in WordPress admin

  • Logged into WordPress, navigate to Taxonomies
  • All blueprint attributes visible as taxonomies
  • Terms correctly organized

---

5.9: Cross-Step Data Flow

• AC-5-7: Data persists through wizard

  • User completes Step 2 (Add Site) → data stored
  • Steps 3a–3f use site_id from Step 2
  • User navigates prev/next → data restored
  • No data loss on page refresh (localStorage/session)

• AC-5-8: Wizard state syncs with backend

  • Blueprint created only after Step 3f confirm
  • Before confirm, blueprint is draft (can be discarded)
  • API calls made in correct order (no race conditions)

---

Non-Functional Criteria

5.10: Performance

• AC-nf-1: Step 3a response time < 2 sec

  • API call to generate-attributes returns in < 2 sec
  • Acceptable for initial page load

• AC-nf-2: Step 3d (AI population) completes < 30 sec

  • LLM call to populate attributes completes within timeout
  • User sees loading indicator (spinner) during processing

• AC-nf-3: Frontend rendering < 1 sec

  • All components (panels, trees, forms) render in < 1 sec
  • No performance degradation with large attribute sets (10+ attributes)

---

5.11: Security

• AC-nf-4: Input validation on all endpoints

  • POST /generate-attributes/ validates industry + sectors
  • POST /populate-attributes/ validates business_data structure
  • POST /generate-blueprint/ validates site_id + attributes
  • POST /confirm-blueprint/ validates blueprint_id + user ownership

• AC-nf-5: User can only access own blueprints

  • Blueprint linked to user's site
  • API checks user ownership before returning/modifying
  • No cross-user data leakage

• AC-nf-6: Business data not exposed publicly

  • business_data input stored securely
  • Not logged or exposed in error messages
  • Sanitized before any external API calls

---

5.12: Accessibility

• AC-nf-7: Components meet WCAG 2.1 AA standard

  • Form labels properly associated (for attribute)
  • ARIA attributes for custom components (tree, expandable sections)
  • Keyboard navigation: tab through form fields, buttons
  • Color not sole indicator (checkmarks, text, icons)
  • Focus indicators visible on all interactive elements

• AC-nf-8: Assistive technology compatible

  • Screen reader announces attribute names, values, completeness status
  • Tree expand/collapse announced
  • Error messages announced

---

5.13: Usability

• AC-nf-9: Error messages are clear and actionable

  • "This field is required" not shown; instead "Please enter at least one product or service"
  • "API error" not shown; instead "Failed to generate attributes. Please check your industry/sectors and try again."
  • Retry buttons provided where applicable

• AC-nf-10: Progress indication is clear

  • Progress bar shows Step 3 of 6
  • Current sub-step indicated (3a, 3b, etc.)
  • User knows where they are and how many steps remain

---

6. CLAUDE CODE INSTRUCTIONS

This section provides step-by-step instructions for Claude Code (or equivalent AI assistant) to implement this document.

6.1 Preparation

1. Review References

   • Read 01A (SAGBlueprint, SAGAttribute model definitions)
   • Read 01B (template_service specification)
   • Read 01C (cluster formation and keyword generation specs)
   • Understand the data flow between models

2. Set Up Environment

   • Clone repository
   • Install dependencies (backend: Django/DRF, frontend: React + Redux, WordPress: plugin SDK)
   • Create feature branch: feature/wizard-step-3-site-structure
   • Ensure tests pass on main branch

6.2 Backend Implementation (In Order)

Task 1: Update Models (1.5 hours)

Location: backend/sag/models.py
- Open SAGBlueprint class
- Add fields: confirmed_at, created_via, wordpress_synced, wordpress_synced_at
- Open SAGAttribute class
- Add fields: level, populated_from_business_data, business_sources, completeness, order
- Create and apply migrations
  python manage.py makemigrations
  python manage.py migrate
- Verify no errors, run existing tests

Task 2: Implement PopulateAttributes AI Function (3 hours)

Location: backend/sag/ai_functions/attribute_population.py
- Create new file
- Implement parse_business_data() function
- Implement map_to_suggested_values() function (with fuzzy matching)
- Implement identify_new_values() function
- Implement assess_completeness() function
- Implement main populate_attributes() orchestrator
- Add docstrings and type hints
- Write unit tests in backend/tests/test_attribute_population.py
- Target: 100% test coverage
- Example test: parse_business_data with comma-separated input
- Example test: fuzzy_match("percussion") → "Percussion Device Type"
- Example test: assess_completeness for various attribute states

Task 3: Implement Wizard API Endpoints (4 hours)

Location: backend/sag/api/views/wizard.py
- Create new file
- Implement WizardGenerateAttributesView (POST /api/v1/sag/wizard/generate-attributes/)
  - Call template_service.get_or_generate_template()
  - Filter attributes, organize by level
  - Return response matching spec
  - Test with different industry/sector combinations

- Implement WizardPopulateAttributesView (POST /api/v1/sag/wizard/populate-attributes/)
  - Call attribute_population.populate_attributes()
  - Handle errors, return populated_attributes
  - Test with sample business data

- Implement WizardGenerateBlueprintView (POST /api/v1/sag/wizard/generate-blueprint/)
  - Create SAGBlueprint record
  - Call cluster_formation.form_clusters()
  - Call keyword_generation.generate()
  - Store results, return blueprint summary
  - Test end-to-end

- Implement WizardConfirmBlueprintView (POST /api/v1/sag/wizard/confirm-blueprint/)
  - Update blueprint status to 'active'
  - Set confirmed_at
  - Emit signal/webhook
  - Test status transition

- Add to backend/sag/api/urls.py routing
- Write unit tests in backend/tests/test_wizard_views.py
- Write integration tests in backend/tests/test_wizard_integration.py

Task 4: Add API Documentation (1 hour)

- Add OpenAPI/Swagger docs for all endpoints
- Include request/response examples
- Document error codes (400, 401, 403, 500, 503)
- Update backend/docs/api.md

6.3 Frontend Implementation (In Order)

Task 5: Implement React Components (6 hours)

Location: frontend/src/components/wizard/

A) WizardStep3Container.jsx (2 hours)
   - Create state object:
     {
       mode: 'quick' | 'detailed',
       currentSubstep: 'generate' | 'review' | 'business' | 'populate' | 'preview' | 'confirm',
       attributes: [],
       businessData: {},
       populatedAttributes: [],
       blueprintData: {}
     }
   - Implement navigation logic (next, prev, skip)
   - Implement conditional rendering of sub-steps based on mode
   - Handle loading/error states
   - Connect to Redux (or context) for wizard state

B) AttributeReviewPanel.jsx (1.5 hours)
   - Render three sections: Primary, Secondary, Tertiary
   - For each attribute: toggle + values + edit/delete + reorder
   - Implement inline edit modal for values
   - Implement "+ Add Custom Attribute" form
   - Show completeness status (ready/thin/empty)

C) BusinessDetailsForm.jsx (1 hour)
   - Five input fields: products, services, brands, locations, conditions
   - Implement text parsing (comma-separated, line-break)
   - Show "x items detected" feedback
   - Implement validation (at least one field, max 50 items)
   - Pass data to parent state on change

D) BlueprintPreviewPanel.jsx (1.5 hours)
   - Render tree view of clusters
   - Each cluster: name, type badge, keyword count, content plan count
   - Expand/collapse per cluster
   - Summary row with totals
   - Action buttons: "Approve & Build", "Adjust Attributes"
   - Handle loading and error states

E) QuickDetailedModeToggle (optional, if not in Step 1)
   - Radio group or card selector
   - Pass selection to WizardStep3Container

Tests:
- Write unit tests for each component (frontend/tests/components/wizard/)
- Test state transitions, user interactions, API calls
- Mock API responses
- Test loading/error states

Task 6: Integrate Wizard Navigation (2 hours)

Location: frontend/src/routes/wizard.js (or similar routing)
- Update router to include Step 3 routes
- Implement navigation logic:
  - Step 1 → Step 2 (always)
  - Step 2 → Step 3 (always)
  - Step 3a → Step 3b (Detailed) or Step 3e (Quick)
  - Step 3b → Step 3c, Step 3c → Step 3d, Step 3d → Step 3e
  - Step 3e → Step 3f, Step 3f → Step 4
- Implement state persistence (Redux or localStorage)
- Test Quick Mode flow and Detailed Mode flow (E2E)

Task 7: Update Step 1 (Welcome) (1 hour)

Location: frontend/src/components/wizard/WizardStep1.jsx (or similar)
- Add mode selection UI (quick vs. detailed)
- Store mode in wizard state (Redux/context)
- Pass mode to WizardStep3Container
- Test mode selection

6.4 WordPress Plugin Integration (2 hours)

Task 8: Enhance Plugin (2 hours)

Location: wordpress-plugin/igny8-blueprint-sync.php (or similar)
- Add listener for blueprint.status = 'active' signal (webhook or Django signal)
- Implement function: create_taxonomies_from_blueprint($blueprint_data)
  - For each attribute in $blueprint_data:
    - Create WordPress taxonomy (if not exists)
    - Create terms from attribute values
    - Set hierarchy based on attribute level
- Test:
  - Create test blueprint with attributes
  - Trigger confirmation
  - Verify taxonomies created in WordPress admin
  - Verify terms match attribute values
  - Verify hierarchy correct

6.5 Testing & QA (6 hours)

Task 9: Unit Testing (2 hours)

- Backend: 80%+ coverage of views, models, AI function
  - Run: python manage.py test backend/tests/
  - Fix any failing tests

- Frontend: 70%+ coverage of components
  - Run: npm test
  - Fix any failing tests

Task 10: Integration Testing (2 hours)

- Backend: test full wizard flow (Steps 3a–3f)
  - Location: backend/tests/test_wizard_integration.py
  - Test Quick Mode scenario
  - Test Detailed Mode scenario
  - Test data persistence and transitions

- Frontend: E2E test both wizard flows
  - Location: frontend/tests/e2e/wizard.test.js (Selenium/Cypress)
  - Test Quick Mode: 10 min, full journey
  - Test Detailed Mode: 20 min, full journey
  - Test error scenarios (invalid input, API failure)

Task 11: UAT & Feedback (2 hours)

- Set up staging environment
- Prepare UAT scenarios:
  1. Massage device ecommerce (Detailed Mode)
  2. Marketing agency (Quick Mode + refine)
  3. B2B service (Detailed Mode + custom attributes)
- Conduct internal UAT with IGNY8 team
- Document feedback
- Fix critical bugs

6.6 Documentation & Deployment (4 hours)

Task 12: Technical Documentation (2 hours)

- Add API docs: backend/docs/api_wizard_endpoints.md
- Add component docs: frontend/docs/wizard_components.md
- Add database schema: docs/database_schema_updates.md
- Add AI function docs: backend/sag/ai_functions/README.md

Task 13: User Documentation (1 hour)

- Create user guide: docs/user_guide_wizard_step3.md
- Screenshots for each sub-step
- Mode comparison table
- FAQ section

Task 14: Deployment (1 hour)

- Merge feature branch to develop
- Create staging deployment
- Test full suite in staging
- Deploy to production with feature flag (optional)
- Monitor logs and error rates
- Support team briefing

6.7 Estimated Effort

Phase	Task	Hours	Notes
Backend	Update Models	1.5	Includes migration
	Implement AI Function	3	Includes tests
	Implement API Endpoints	4	Includes tests
	API Docs	1
Frontend	React Components	6	5 components + tests
	Wizard Navigation	2	Includes state management
	Step 1 Update	1	Mode toggle
WordPress	Plugin Enhancement	2	Taxonomy creation
QA	Unit Testing	2	Coverage targets
	Integration Testing	2	E2E scenarios
	UAT	2	Feedback and fixes
Docs	Technical + User Docs	3	Guides, screenshots, API
Deploy	Deployment & Monitoring	1
Total		31 hours	~1 week (4 developers)

6.8 Key Checkpoints

1. After Backend (Hour 10)

   • All API endpoints tested and documented
   • PopulateAttributes AI function working end-to-end
   • Models migrated successfully

2. After Frontend (Hour 22)

   • All components integrated, wizard flow works
   • Quick and Detailed modes fully functional
   • E2E tests passing

3. After Plugin (Hour 24)

   • WordPress taxonomies auto-created on blueprint confirmation
   • Manual verification in WordPress admin

4. After QA (Hour 30)

   • 80%+ unit test coverage
   • Integration tests passing
   • UAT feedback resolved

5. After Docs & Deploy (Hour 31)

   • All documentation complete
   • Feature deployed to production
   • Monitoring in place

---

REFERENCES

• 01A: SAGBlueprint & SAGAttribute Model Definitions
• 01B: Template Service Specification (sector-based attribute templates)
• 01C: Cluster Formation & Keyword Generation Specification
• 01E: Content Pipeline (receives blueprint output)
• 01F: Case 1 (Existing Site) — alternative onboarding path
• 01G: Health Monitoring & Blueprint Tracking

---

REVISION HISTORY

Version	Date	Author	Change
1.0	2026-03-23	System	Initial draft

---

Document Owner: IGNY8 Product Team Status: Ready for Implementation Next Review: Upon completion of Phase 1 (Mid-April 2026)