# Phase 4 Build Plan — Business Layer (3 Docs)

**Purpose:** This is a single instruction set for Claude Code to build all 3 Phase 4 execution documents. Read this entire file, then build each doc one at a time.

---

## CRITICAL BASELINE RULES (from V2-Execution-Docs-Updated)

Before writing ANY doc, internalize these codebase-verified facts:

### Primary Keys
- ALL models use `BigAutoField` (integer PKs, NOT UUIDs)
- `DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'`
- Every ID in API requests/responses is an integer

### Model Names (PLURAL)
- `Clusters` (not Cluster), `Keywords` (not Keyword), `Tasks` (not Task)
- `ContentIdeas` (not ContentIdea), `Images` (not Image), `Content` (stays singular)

### App Structure
- Project root: `igny8_core/`
- SAG app: `igny8_core/sag/`
- App labels: `igny8_core_auth`, `planner`, `writer`, `automation`, `integration`, etc.
- All tables use `igny8_` prefix

### Verified Codebase Versions
- Python 3.11, Django >=5.2.7, Node 18, React ^19.0.0, TypeScript ~5.7.2, Zustand ^5.0.8, Vite ^6.1.0, Celery >=5.3.0

### Model Inheritance
- `AccountBaseModel` provides: `account` FK, `created_by`, `created_at`, `updated_at`
- `SiteSectorBaseModel` extends AccountBaseModel with: `site` FK, `sector` FK
- `SoftDeletableModel` mixin provides soft delete via `SoftDeleteManager`

### Frontend Stack
- TypeScript `.tsx` files, Zustand state management, Vitest + Playwright testing

### Source of Truth
- Start every doc with: `**Source of Truth:** Codebase at /data/app/igny8/`

---

## DOC STRUCTURE STANDARD

Every doc MUST follow this structure:

```
# [Phase.Sub] — Title
**Source of Truth:** Codebase at `/data/app/igny8/`
**Version:** 1.0
**Date:** 2026-03-23

## 1. Current State
## 2. What to Build
## 3. Data Models & APIs
## 4. Implementation Steps
## 5. Acceptance Criteria
## 6. Claude Code Instructions
```

---

## EXISTING BILLING CONTEXT (Phase 4 builds on top of this)

### Existing Billing Models (billing app)
- `Plan` — subscription tier definition (Free/$49/$149/$349)
- `Subscription` — active subscription per account, links to Plan
- `CreditTransaction` — individual credit debit/credit events
- `CreditUsageLog` — per-operation usage tracking
- `CreditCostConfig` — configurable cost per operation type
- `AccountPaymentMethod` — saved Stripe/PayPal payment methods
- `Payment` — payment records
- `Invoice` — invoice records

### Existing Credit System
- `CreditService` in `business/billing/` manages all credit operations
- Pattern: `check_credits()` → execute operation → `deduct_credits()` → `log_usage()`
- `AIModelConfig.tokens_per_credit` (text) and `credits_per_image` (images)

### Current Plans (live)
| Plan | Price | Sites | Users | Credits/Month |
|------|-------|-------|-------|---------------|
| Free | $0 | 1 | 1 | 100 |
| Starter | $49 | 3 | 3 | 1,000 |
| Growth | $149 | 10 | 10 | 5,000 |
| Scale | $349 | Unlimited | Unlimited | 25,000 |

### Payment Infrastructure
- Stripe + PayPal integrated (live credentials)
- Manual payment methods available
- Existing webhook handlers for subscription events

### Existing Integration Infrastructure
- `SiteIntegration` — stores WordPress + other connections
- `SyncEvent` — logs sync operations
- `IntegrationProvider` — provider definitions (OpenAI, Anthropic, Runware, etc.)
- `IntegrationSettings` — per-account provider settings

### Phase 2 Models Phase 4 Depends On
- `SAGCampaign`, `SAGBacklink`, `CampaignKPISnapshot` (02E — backlink engine)
- `GSCConnection`, `URLInspectionRecord`, `GSCMetricsCache` (02C — GSC data)
- `SAGLink`, `SAGLinkAudit`, `LinkMap` (02D — internal linking)
- `SocialPost`, `SocialAccount`, `SocialEngagement` (02H — socializer)
- `SchemaTemplate`, `SERPEnhancement`, `SchemaValidationResult` (02G — schema)
- `SAGBlueprint`, `SAGAttribute`, `SAGCluster` (01A — SAG core)
- `AutomationConfig`, `AutomationRun` (automation app)

---

## DOC 04A: managed-services.md

**File:** `V2-Execution-Docs/04A-managed-services.md`
**Scope:** Managed service tiers (Lite/Pro), backlink service packages, Ahrefs API integration, backlink indexing service, client onboarding automation, service delivery workflows, admin dashboard.
**Depends On:** 02E (backlink campaign engine) + 03B (WP plugin connected mode)

### Source Material:
- Live Docs on Server/igny8-app-docs/plans/final-dev-guides-of-futute-implementation/DocD-Business-Services-Dev-Guide.md
- temp/IGNY8-Project-Files/SAG-Doc4-External-Backlink-Campaign-PLAN.md (managed service pricing)

### What to Cover:

**1. Current State:**
- Billing infrastructure exists (Plan, Subscription, CreditTransaction, Payment, Invoice)
- Stripe/PayPal integrated and live
- No managed services layer — Alorig manages client sites manually
- No backlink order tracking — orders placed manually on FatGrid/PRNews
- No automated reporting — reports created manually
- No Ahrefs integration — domain/backlink data checked manually in Ahrefs dashboard
- No backlink indexing service — links indexed organically or manually submitted
- 6 existing Alorig clients ready for managed service conversion

**2. What to Build:**

**Managed Service Tiers:**

**Managed Lite ($100/site/month):**
- 10 articles/month (published to WordPress via pipeline)
- Basic SAG setup + automation configuration (first month)
- Monthly PDF report
- Email support (48-hour response)
- Automation config: weekly schedule, 3 articles/run, post + cluster_hub types
- Review required before publish (Alorig team reviews in Writer)

**Managed Pro ($399/site/month):**
- 30 articles/month (hubs prioritized early, supporting content later)
- Full SAG architecture with detailed mode
- Backlink campaign management (budget separate, pass-through + 20% markup)
- Social media content generation + scheduling (configured platforms)
- Retroactive schema enhancement on existing pages
- GSC monitoring: auto-indexing, re-inspection, issue alerts
- Weekly PDF report with full KPIs
- Dedicated account manager (24-hour response)
- Taxonomy term content generation

**Backlink Service Packages (Managed Mode — Alorig Executes):**

By quality level:
| Tier | Service | Alorig Cost | Client Price | Margin |
|------|---------|-------------|-------------|--------|
| Basic Guest Post | DR 30-50 via FatGrid | $30-80 | $150-300 | 3-5× |
| Standard Guest Post | DR 50-70 via FatGrid | $100-300 | $400-800 | 2-3× |
| Premium Guest Post | DR 70+ via FatGrid | $500-2,000 | $1,500-5,000 | 2-3× |
| PR Basic | 300+ outlets via EIN Presswire | $99-499 | $500-1,500 | 3-5× |
| PR Premium | Yahoo/Bloomberg/Fox via PRNews.io/Linking News | $500-5,000 | $2,000-15,000 | 3-4× |

Monthly retainer packages:
| Package | Links/Month | DR Range | Monthly Cost | Market |
|---------|------------|----------|-------------|--------|
| Starter | 5-8 links | DR 30-50 | $800-1,500 | PK market |
| Growth | 10-15 links | DR 30-70 mix | $2,000-4,000 | UK/CA market |
| Authority | 15-25 links | DR 40-70+ mix + PR | $4,000-8,000 | USA market |
| Enterprise | Custom | Custom | Custom | Multi-site/agency |

Niche surcharges: Crypto/Casino 2-3×, Finance/Insurance 1.5-2×, Health/Medical 1.5-2×, Tech/SaaS 1.2-1.5×, General 1× baseline.

**Ahrefs API Integration (NEW — not in original planning docs):**

IGNY8 integrates with Ahrefs API v3 for automated domain metrics, backlink monitoring, and competitive intelligence. This serves both the managed services reporting and the self-service backlink module.

Ahrefs API endpoints to integrate:
- `GET /v3/site-explorer/domain-rating` — DR for any domain (used in backlink quality scoring)
- `GET /v3/site-explorer/backlinks` — all backlinks to a target URL/domain (verify placed links)
- `GET /v3/site-explorer/referring-domains` — referring domain list + metrics
- `GET /v3/site-explorer/organic-keywords` — organic keyword rankings (supplement GSC data)
- `GET /v3/site-explorer/pages-by-traffic` — top pages by organic traffic
- `GET /v3/site-explorer/metrics` — domain metrics summary (DR, referring domains, organic traffic, organic keywords)
- `GET /v3/site-explorer/metrics-history` — historical domain metrics (DR trend, traffic trend)
- `GET /v3/site-explorer/refdomains-history` — referring domains over time

Use cases in IGNY8:
1. **Backlink verification** — after SAGBacklink is placed, verify it's live via Ahrefs crawl data (supplements HTTP check)
2. **Quality scoring** — auto-populate source_dr, source_traffic on SAGBacklink from Ahrefs
3. **Campaign KPIs** — pull DR, referring domains, organic keywords for CampaignKPISnapshot automatically
4. **Competitor analysis** — compare client's domain metrics against competitors
5. **Dead link detection** — cross-reference Ahrefs lost backlinks with SAGBacklink records
6. **Reporting** — Ahrefs metrics feed into ServiceReport data (DR history, referring domain growth, top pages)
7. **Link prospecting** — find competitor backlinks for outreach opportunities

Ahrefs API pricing: credits-based (varies by plan), IGNY8 stores API key per account in IntegrationSettings.

**Backlink Indexing Service (NEW — not in original planning docs):**

After a backlink is placed and verified live, it needs to be crawled by Google to pass authority. Natural indexing can take weeks/months. IGNY8 integrates an on-demand backlink indexing service.

Indexing service options (integrate best available):
- **IndexNow API** (free) — submit URLs to Bing/Yandex (not Google, but signals exist)
- **Google Indexing API** — only for JobPosting/BroadcastEvent pages (limited use)
- **Omega Indexer** — bulk indexing service, API available, ~$0.02-0.05/URL
- **Colossus Indexer** — high success rate, ~$0.03-0.07/URL
- **SpeedyIndex** — fast indexing, API available, credit-based pricing
- **LinkCentaur** — drip-feed indexing, API available

Recommended primary: **SpeedyIndex or Omega Indexer** (both have APIs, reasonable pricing, good success rates)

Integration flow:
```
SAGBacklink status changes to 'live'
  → Verify URL is accessible (HTTP 200)
  → Queue for indexing service submission
  → Submit via indexing service API
  → Track: submitted_for_indexing_at, indexing_service, indexing_status
  → Check back after 7 days (Ahrefs or HTTP cache header check)
  → If indexed → update SAGBacklink.is_indexed = True
  → If not after 14 days → re-submit once
  → If still not after 28 days → mark as indexing_failed, flag for review
```

Client-facing: "Indexing Boost" add-on or included in Pro tier
Pricing to client: $0.10-0.20 per URL (5-10× markup on service cost)

**Client Onboarding Automation:**

When `ManagedServiceSubscription` is created:
1. Check site has IGNY8 plugin installed + connected (verify `SiteIntegration` exists)
2. If no blueprint → queue Celery task to run SAG wizard (auto-generate blueprint)
3. Configure `AutomationConfig` based on service_config (schedule, stages, content types)
4. Send welcome email to client (what to expect, how to approve content, contact info)
5. Create first month content tasks in pipeline queue
6. Notify account manager: "New client onboarded, first content due"
7. Update subscription status: pending → active

Monthly delivery workflow (Lite):
```
Month Start → Check blueprint exists → Run pipeline (10 articles) →
Alorig reviews → Approve/edit → Publish to WP →
Update articles_published counter → Month End → Generate report → Send → Bill
```

Monthly delivery workflow (Pro — adds to Lite):
```
+ Run pipeline for 30 articles (hubs first) + Taxonomy term content
+ Backlink: Load SAGCampaign monthly plan → Browse FatGrid → Place orders →
  Track delivery → Quality check → Log SAGBacklink → Submit for indexing
+ Social: Generate platform-adapted posts → Schedule via best-time algorithm
+ Schema: Run retroactive scan → Push to WP
+ GSC: Check indexing → Re-request pending → Flag issues
+ Weekly: Generate report → Send
```

**3. Data Models & APIs:**

New models (in new `services` app):

- `ManagedServiceSubscription` (extends AccountBaseModel)
  - `site` ForeignKey to Site
  - `tier` CharField (lite/pro)
  - `status` CharField (pending/active/paused/cancelled)
  - `monthly_price` DecimalField(max_digits=8, decimal_places=2)
  - `articles_per_month` IntegerField
  - `account_manager` ForeignKey to User (nullable) — assigned team member
  - `current_month_articles_published` IntegerField (default 0)
  - `current_month_start` DateField (nullable)
  - `service_config` JSONField — per-site settings (automation, social, backlinks, reporting)
  - `started_at` DateTimeField (nullable)
  - `cancelled_at` DateTimeField (nullable)
  - `next_billing_date` DateField (nullable)
  - Table: `igny8_managed_service_subscriptions`

- `BacklinkServiceOrder` (extends AccountBaseModel)
  - `site` ForeignKey to Site
  - `campaign` ForeignKey to SAGCampaign (nullable)
  - `managed_subscription` ForeignKey to ManagedServiceSubscription (nullable)
  - `order_type` CharField (one_time/monthly)
  - `package` CharField (starter/growth/authority/enterprise/custom)
  - `client_price` DecimalField(max_digits=10, decimal_places=2)
  - `actual_cost` DecimalField(max_digits=10, decimal_places=2, default=0)
  - `margin` DecimalField(max_digits=10, decimal_places=2, default=0)
  - `niche_surcharge` FloatField (default 1.0)
  - `links_ordered` IntegerField (default 0)
  - `links_delivered` IntegerField (default 0)
  - `links_live` IntegerField (default 0)
  - `links_indexed` IntegerField (default 0)
  - `status` CharField (draft/approved/in_progress/delivered/completed)
  - `ordered_at` DateTimeField (nullable)
  - `delivered_at` DateTimeField (nullable)
  - `notes` TextField (blank)
  - Table: `igny8_backlink_service_orders`

- `AhrefsConnection` (extends AccountBaseModel)
  - `api_key` TextField (encrypted)
  - `plan_type` CharField (nullable) — lite/standard/advanced/enterprise
  - `credits_remaining` IntegerField (nullable)
  - `last_synced` DateTimeField (nullable)
  - `status` CharField (active/expired/error)
  - Table: `igny8_ahrefs_connections`

- `AhrefsDomainSnapshot` (extends SiteSectorBaseModel)
  - `domain` CharField
  - `domain_rating` FloatField
  - `referring_domains` IntegerField
  - `organic_keywords` IntegerField
  - `organic_traffic` IntegerField
  - `backlinks_total` IntegerField
  - `snapshot_date` DateField
  - `raw_data` JSONField — full API response
  - Table: `igny8_ahrefs_domain_snapshots`

- `BacklinkIndexingRequest` (extends SiteSectorBaseModel)
  - `backlink` ForeignKey to SAGBacklink
  - `url` URLField — the backlink source URL to be indexed
  - `indexing_service` CharField (speedyindex/omega/colossus/indexnow/manual)
  - `service_request_id` CharField (nullable) — external service reference
  - `submitted_at` DateTimeField (nullable)
  - `first_check_at` DateTimeField (nullable)
  - `last_check_at` DateTimeField (nullable)
  - `check_count` IntegerField (default 0)
  - `is_indexed` BooleanField (default False)
  - `indexed_at` DateTimeField (nullable)
  - `status` CharField (queued/submitted/checking/indexed/failed/resubmitted)
  - `cost` DecimalField(max_digits=6, decimal_places=4, default=0)
  - Table: `igny8_backlink_indexing_requests`

Modified models:
- `SAGBacklink` (from 02E) — add fields:
  - `is_indexed` BooleanField (default False)
  - `indexed_at` DateTimeField (nullable)
  - `ahrefs_verified` BooleanField (default False)
  - `ahrefs_last_seen` DateTimeField (nullable)
  - `indexing_submitted` BooleanField (default False)

New endpoints:

```
# Managed Service Subscriptions
GET    /api/v1/services/subscriptions/                        # List (admin only)
POST   /api/v1/services/subscriptions/                        # Create
GET    /api/v1/services/subscriptions/{id}/                   # Detail
PATCH  /api/v1/services/subscriptions/{id}/                   # Update config/status
POST   /api/v1/services/subscriptions/{id}/onboard/           # Trigger onboarding flow
POST   /api/v1/services/subscriptions/{id}/pause/             # Pause service
POST   /api/v1/services/subscriptions/{id}/resume/            # Resume service
POST   /api/v1/services/subscriptions/{id}/cancel/            # Cancel service

# Backlink Service Orders
GET    /api/v1/services/backlink-orders/                      # List (admin)
POST   /api/v1/services/backlink-orders/                      # Create order
GET    /api/v1/services/backlink-orders/{id}/                 # Detail
PATCH  /api/v1/services/backlink-orders/{id}/                 # Update status/details
GET    /api/v1/services/backlink-orders/{id}/links/           # Links in this order
POST   /api/v1/services/backlink-orders/{id}/approve/         # Client approves order

# Ahrefs Integration
POST   /api/v1/integration/ahrefs/connect/                    # Save API key
DELETE /api/v1/integration/ahrefs/disconnect/                  # Remove connection
GET    /api/v1/integration/ahrefs/status/                     # Connection status + credits
GET    /api/v1/integration/ahrefs/domain/{domain}/            # Domain metrics (proxy)
GET    /api/v1/integration/ahrefs/domain/{domain}/history/    # DR + traffic history
GET    /api/v1/integration/ahrefs/backlinks/{domain}/         # Backlinks list
GET    /api/v1/integration/ahrefs/referring-domains/{domain}/ # Referring domains
GET    /api/v1/integration/ahrefs/organic-keywords/{domain}/  # Organic keywords
POST   /api/v1/integration/ahrefs/verify-backlinks/           # Bulk verify SAGBacklinks via Ahrefs
POST   /api/v1/integration/ahrefs/snapshot/                   # Take domain snapshot for KPIs

# Backlink Indexing
POST   /api/v1/linker/indexing/submit/                        # Submit URLs for indexing
POST   /api/v1/linker/indexing/bulk-submit/                   # Bulk submit (all live unindexed)
GET    /api/v1/linker/indexing/requests/?site_id=X            # List indexing requests
GET    /api/v1/linker/indexing/requests/{id}/                 # Single request status
GET    /api/v1/linker/indexing/stats/?site_id=X               # Indexing success rate, pending count

# Admin Dashboard
GET    /api/v1/services/dashboard/                            # Revenue summary, client count, MRR
GET    /api/v1/services/dashboard/overdue/                    # Overdue content/links deliverables
GET    /api/v1/services/dashboard/margin/                     # Margin tracking across all orders
```

Celery tasks:
- `onboard_managed_client` — triggered on subscription creation, runs full onboarding
- `process_managed_billing` — monthly, invoice all active subscriptions
- `reset_monthly_counters` — monthly, reset articles_published counters
- `check_delivery_status` — daily, flag subscriptions behind on content/links
- `sync_ahrefs_domain_snapshot` — weekly per connected site, pull DR/traffic/etc.
- `verify_backlinks_via_ahrefs` — weekly, cross-reference SAGBacklink records with Ahrefs data
- `submit_backlinks_for_indexing` — daily, submit live unindexed backlinks to indexing service
- `check_indexing_status` — daily, check submitted URLs (after 7-day wait)
- `detect_lost_backlinks_ahrefs` — weekly, compare Ahrefs data with SAGBacklink records

Services:
- `ManagedBillingService` — subscription CRUD, billing, margin calculation
- `AhrefsService` — API client wrapper, rate limiting, credit tracking
- `BacklinkIndexingService` — submit to indexing service, track status, retry logic

**Margin Analysis:**
| Component | Managed Lite | Managed Pro |
|-----------|-------------|-------------|
| Service Fee | $100/month | $399/month |
| Platform Cost (credits) | ~$15-25 | ~$50-80 |
| Human Time | ~2-3 hrs/month | ~8-12 hrs/month |
| Ahrefs API cost | ~$2-5 | ~$10-20 |
| Indexing service cost | $0 | ~$5-15 |
| Gross Margin | ~70-75% | ~65-75% |

Note: Backlink purchase costs are pass-through with 20% markup — separate from service fee.

**Cross-references:** 02E (SAGCampaign/SAGBacklink models), 02C (GSC data for indexing status), 02D (internal linking health), 02H (socializer for Pro tier), 02G (schema enhancement for Pro tier), 01A (SAGBlueprint for onboarding), 03B (WP plugin connected for content delivery)

---

## DOC 04B: whitelabel-reporting.md

**File:** `V2-Execution-Docs/04B-whitelabel-reporting.md`
**Scope:** Agency account model, automated report generation (weekly/monthly/quarterly), white-label branding, admin services dashboard, client-facing read-only view, PDF report templates, Linking News white-label integration.
**Depends On:** 04A (managed services provides subscriptions + order data)

### Source Material:
- Live Docs on Server/igny8-app-docs/plans/final-dev-guides-of-futute-implementation/DocD-Business-Services-Dev-Guide.md

### What to Cover:

**1. Current State:**
- No reporting infrastructure in IGNY8
- No agency/reseller model
- No white-label capability
- Reports created manually by Alorig team (Google Docs/Sheets)
- No admin dashboard for managed service oversight

**2. What to Build:**

**Report Generation Engine:**

9 configurable report sections (each can be included/excluded per client):
1. **Executive Summary** — key wins, KPI highlights, AI-generated summary paragraph
2. **Content Performance** — articles published (count, by type), word count, images created
3. **Indexing Status** — pages indexed/pending/error (from GSC 02C), trend chart
4. **Keyword Rankings** — keywords in top 10/20/50, position movers up/down, new entries (from GSC + Ahrefs)
5. **Organic Traffic** — clicks, impressions, CTR, avg position (from GSC), month-over-month change
6. **Backlink Campaign** (if active) — links built, DR distribution chart, budget spent vs allocated, quality scores, Ahrefs referring domain growth
7. **Social Media** (if active) — posts published by platform, engagement (likes/comments/shares), top performers
8. **SAG Health** — overall blueprint completion %, cluster status, authority score (0-100), content gaps remaining
9. **Next Month Plan** — upcoming content topics, backlink targets, action items for client approval

Data sources per section:
- Content: `Content` model (writer app) filtered by site + date range
- Indexing: `URLInspectionRecord` (02C) + `GSCMetricsCache`
- Rankings: `GSCMetricsCache` (02C) + `AhrefsDomainSnapshot` (04A)
- Traffic: `GSCMetricsCache` (02C)
- Backlinks: `SAGBacklink` (02E) + `BacklinkServiceOrder` (04A) + `CampaignKPISnapshot` (02E) + `AhrefsDomainSnapshot` (04A)
- Social: `SocialPost` + `SocialEngagement` (02H)
- SAG Health: `SAGBlueprint` health score (01G)
- Next Month: `SAGCampaign` monthly plan (02E) + automation queue

**PDF Report Generation:**
- Template engine: WeasyPrint (HTML → PDF) or ReportLab
- Base HTML template with CSS styling
- Sections rendered conditionally based on client config
- Charts rendered via matplotlib or chart.js (server-side rendering)
- Output stored in S3/media storage, URL saved in `ServiceReport.report_pdf_url`
- Template supports light/dark themes

**White-Label Branding (Agency Play):**

For agencies reselling IGNY8 services to their clients:
- `AgencyBranding` model stores: agency name, logo URL, primary color, secondary color, contact email, contact phone, website URL, footer text
- When `ServiceReport.is_white_label = True`:
  - "IGNY8" / "Alorig" replaced with `brand_name` throughout PDF
  - Logo replaced with `brand_logo_url` in header
  - Footer shows agency contact info
  - Color scheme uses agency brand colors
  - Report URL domain can be custom (via Caddy subdomain routing)
- Linking News integration: white-label PR distribution reports use agency branding

**Admin Services Dashboard (Alorig team only):**

Frontend pages (TypeScript .tsx):
```
frontend/src/pages/Services/
├── ServicesDashboard.tsx          # Overview: all managed clients, MRR, revenue
│   ├── ClientList.tsx             # All subscriptions with status, tier, articles count
│   ├── RevenueSummary.tsx         # MRR total, margin total, trend chart
│   └── UpcomingActions.tsx        # Overdue: reports, content, renewals
├── ClientDetail.tsx               # Single client management
│   ├── ClientConfig.tsx           # Service config editor (JSON form)
│   ├── ContentTracker.tsx         # Articles published this month vs target
│   ├── BacklinkTracker.tsx        # Links ordered vs delivered vs live vs indexed
│   ├── AhrefsMetrics.tsx          # DR history, referring domains, top pages
│   ├── ReportHistory.tsx          # Past reports with resend option
│   └── BillingHistory.tsx         # Invoices, payments, margin per order
├── BacklinkOrders.tsx             # All orders across clients
│   ├── OrderList.tsx              # Filterable by client, status, package
│   └── OrderDetail.tsx            # Individual order with link-by-link tracking
├── IndexingDashboard.tsx          # Backlink indexing status across all clients
└── ReportGenerator.tsx            # Generate report for any client + period
```

Sidebar addition (admin-only, behind `managed_services_enabled` feature flag):
```
ADMIN
  ├── Sector Templates
  └── Managed Services (NEW)
```

**Client-Facing View (for managed clients who also have IGNY8 access):**

Frontend pages:
```
frontend/src/pages/ManagedService/
├── ServiceOverview.tsx            # What's included, current month progress
├── ReportViewer.tsx               # View/download past reports
└── ApprovalQueue.tsx              # Approve blueprint, review content (if review_required)
```

Sidebar addition (only shows if `ManagedServiceSubscription` exists for account):
```
ACCOUNT
  ├── Account Settings
  ├── Plans & Billing
  ├── Managed Service (NEW — conditional)
  ├── Usage
  └── AI Models
```

**3. Data Models & APIs:**

New models (in `services` app):

- `ServiceReport` (extends AccountBaseModel)
  - `site` ForeignKey to Site
  - `managed_subscription` ForeignKey to ManagedServiceSubscription (nullable)
  - `report_type` CharField (weekly/monthly/quarterly)
  - `period_start` DateField
  - `period_end` DateField
  - `report_data` JSONField — all metrics for period (structured by section)
  - `report_pdf_url` URLField (blank) — generated PDF in S3
  - `is_white_label` BooleanField (default False)
  - `branding` ForeignKey to AgencyBranding (nullable)
  - `sections_included` JSONField — list of included section keys
  - `generated_at` DateTimeField (auto_now_add)
  - `sent_at` DateTimeField (nullable)
  - `sent_to` JSONField — list of email addresses sent to
  - Table: `igny8_service_reports`

- `AgencyBranding` (extends AccountBaseModel)
  - `brand_name` CharField(max_length=200)
  - `brand_logo_url` URLField (blank)
  - `primary_color` CharField(max_length=7) — hex color
  - `secondary_color` CharField(max_length=7) — hex color
  - `contact_email` EmailField (blank)
  - `contact_phone` CharField (blank)
  - `website_url` URLField (blank)
  - `footer_text` TextField (blank)
  - `is_active` BooleanField (default True)
  - Table: `igny8_agency_branding`

- `ReportTemplate` (extends AccountBaseModel)
  - `name` CharField
  - `template_html` TextField — base HTML template
  - `template_css` TextField — custom CSS
  - `is_default` BooleanField
  - `branding` ForeignKey to AgencyBranding (nullable) — agency-specific template
  - Table: `igny8_report_templates`

New endpoints:

```
# Service Reports
GET    /api/v1/services/reports/                              # List (admin + client's own)
POST   /api/v1/services/reports/generate/                     # Generate report
GET    /api/v1/services/reports/{id}/                         # Detail + PDF URL
POST   /api/v1/services/reports/{id}/send/                    # Email to recipients
POST   /api/v1/services/reports/{id}/regenerate/              # Regenerate PDF
GET    /api/v1/services/reports/preview/                      # Preview with data (no save)

# Agency Branding
GET    /api/v1/services/branding/                             # List brandings
POST   /api/v1/services/branding/                             # Create branding
GET    /api/v1/services/branding/{id}/                        # Detail
PUT    /api/v1/services/branding/{id}/                        # Update
DELETE /api/v1/services/branding/{id}/                        # Delete

# Report Templates
GET    /api/v1/services/report-templates/                     # List templates
POST   /api/v1/services/report-templates/                     # Create custom template
PUT    /api/v1/services/report-templates/{id}/                # Update template

# Dashboard (Admin)
GET    /api/v1/services/dashboard/                            # Revenue, clients, MRR
GET    /api/v1/services/dashboard/overdue/                    # Overdue deliverables
GET    /api/v1/services/dashboard/margin/                     # Margin tracking
GET    /api/v1/services/dashboard/clients/                    # Client list with status summary
```

Celery tasks:
- `generate_weekly_reports` — every Monday 6am, generate for all Pro clients
- `generate_monthly_reports` — 1st of month, generate for all Lite + Pro clients
- `send_pending_reports` — daily, email any generated but unsent reports
- `check_overdue_deliverables` — daily, flag clients behind on content/links
- `collect_report_metrics` — nightly, pre-aggregate metrics for faster report generation

Services:
- `ReportService` — generate_report(), collect metrics from all sources, render PDF
- `ReportEmailService` — send report emails with PDF attachment or link

**Cross-references:** 04A (subscription + order data feeds reports), 02C (GSC data), 02E (backlink KPIs), 02H (social metrics), 01G (SAG health), 04C (feature flags control access)

---

## DOC 04C: pricing-launch.md

**File:** `V2-Execution-Docs/04C-pricing-launch.md`
**Scope:** Updated plan pricing structure, feature gating (which features at which plan level), WordPress.org plugin submission, go-to-market strategy, launch sequence, existing user migration.
**Depends On:** 04B (reporting and agency features complete)

### Source Material:
- Live Docs on Server/igny8-app-docs/plans/final-dev-guides-of-futute-implementation/DocD-Business-Services-Dev-Guide.md
- temp/IGNY8-Project-Files/IGNY8-Current-State.md (current plan structure)

### What to Cover:

**1. Current State:**
- 4 plans live (Free/$49/$149/$349)
- Stripe + PayPal integrated
- Feature gating exists via `Plan` model but minimal differentiation
- No WordPress.org submission done
- No formal go-to-market — current clients are direct Alorig relationships
- No managed services add-ons in billing flow

**2. What to Build:**

**Updated Plan Feature Matrix:**

Core SaaS plans remain unchanged in price. New V2 features are gated by plan:

| Feature | Free | Starter ($49) | Growth ($149) | Scale ($349) |
|---------|------|--------------|---------------|-------------|
| Sites | 1 | 3 | 10 | Unlimited |
| Credits/month | 100 | 1,000 | 5,000 | 25,000 |
| SAG Blueprint | Quick mode only | Quick + Detailed | Full | Full |
| Content Types | Post only | Post + Page | All types | All types |
| Taxonomy Content | — | — | ✓ | ✓ |
| GSC Integration | — | Basic (analytics only) | Full (+ indexing) | Full |
| Internal Linker | — | Audit only | Audit + auto-insert | Full + remediation |
| External Backlinks | — | — | Self-service | Self-service + API |
| Optimizer | — | Basic analysis | Full rewrite | Full + batch |
| Rich Schema | Basic (Article only) | 5 types | All 10 types | All + retroactive |
| Socializer | — | 2 platforms | All platforms | All + auto-schedule |
| Video Creator | — | — | Short-form only | All formats |
| Ahrefs Integration | — | — | Read-only metrics | Full (verify + prospect) |
| Backlink Indexing | — | — | — | ✓ (included) |
| Reports | — | — | Monthly PDF | Weekly + custom |
| White-Label | — | — | — | ✓ |
| API Access | — | — | Read-only | Full CRUD |
| Managed Services | — | — | Can purchase Lite | Can purchase Lite/Pro |

**Feature Flag System:**

Extend existing `Plan` model with feature capabilities:

New model: `PlanFeature` (or JSON field on Plan):
```
plan_features = {
    "sag_mode": "quick|detailed|full",
    "content_types": ["post"] | ["post", "page"] | "all",
    "taxonomy_content": false | true,
    "gsc_level": "none|basic|full",
    "linker_level": "none|audit|auto|full",
    "backlinks_level": "none|self_service|self_service_api",
    "optimizer_level": "none|basic|full|batch",
    "schema_types": 0 | 5 | 10 | "all_retroactive",
    "socializer_platforms": 0 | 2 | "all" | "all_auto",
    "video_level": "none|short|all",
    "ahrefs_level": "none|readonly|full",
    "backlink_indexing": false | true,
    "report_level": "none|monthly|weekly_custom",
    "white_label": false | true,
    "api_access": "none|readonly|full",
    "managed_services": "none|lite|lite_pro"
}
```

Feature gate checking pattern:
```python
# In any ViewSet or service
def check_feature(account, feature, required_level):
    plan = account.subscription.plan
    features = plan.plan_features  # JSONField
    current = features.get(feature, "none")
    return LEVEL_HIERARCHY[feature].index(current) >= LEVEL_HIERARCHY[feature].index(required_level)
```

Middleware/decorator:
```python
@require_feature('linker_level', 'auto')
def auto_insert_links(self, request):
    ...
```

**Managed Services Add-On Pricing (in billing flow):**

| Add-On | Price | Available To |
|--------|-------|-------------|
| Managed Lite | $100/site/month | Growth + Scale plans |
| Managed Pro | $399/site/month | Scale plan only |
| Backlink Package (Starter) | $800-1,500/month | Growth + Scale |
| Backlink Package (Growth) | $2,000-4,000/month | Growth + Scale |
| Backlink Package (Authority) | $4,000-8,000/month | Scale only |
| Indexing Boost (standalone) | $0.15/URL | Growth + Scale |

**WordPress.org Plugin Submission:**

Plugin: IGNY8 SEO (standalone plugin from 03A, rebranded for WP.org)
Slug: `igny8-seo`
Version: 2.0.0

Submission checklist:
1. Code review: sanitization (all inputs), escaping (all outputs), nonce verification (all forms)
2. No external calls without user consent (phone-home disabled by default)
3. GPL v2+ license file included
4. readme.txt formatted per WP.org standards (short description, installation, FAQ, changelog, screenshots)
5. Assets: plugin banner (1544×500 and 772×250), icon (256×256 and 128×128), 8+ screenshots
6. Translation-ready: all strings wrapped in `__()`, `_e()`, `esc_html__()` with `igny8` text domain
7. No minified JS without source (include unminified versions)
8. Security: no direct file access without `ABSPATH` check, no `eval()`, no `file_get_contents()` for remote
9. Privacy: no tracking without consent, no storing user IPs (hash only)
10. Performance: no admin-wide asset loading, conditional enqueue

Review timeline: typically 1-4 weeks for initial review

Post-approval:
- Set up SVN deploy pipeline (GitHub → WP.org SVN)
- Auto-deploy on version tag via GitHub Actions
- Update checker: existing `/api/plugins/{slug}/check-update/` endpoint continues working for connected users

**Go-to-Market Strategy:**

Target audiences:
1. **WordPress site owners** — discover via WP.org plugin directory, free plugin → upsell to SaaS
2. **SEO agencies** — managed services + white-label, scale with backlink packages
3. **Content creators/bloggers** — SAG-powered content strategy, AI content generation
4. **eCommerce stores** — WooCommerce integration, product schema, service pages
5. **Local businesses** — LocalBusiness schema, service area pages, GSC monitoring

Funnel:
```
WP.org Plugin (free) → Install → Setup Wizard →
  → Free Plan (limited, 100 credits) → Experience value →
  → Upgrade to Starter/Growth/Scale →
  → Optional: Purchase Managed Services add-on →
  → Optional: Purchase Backlink Packages
```

**Launch Sequence:**

Phase 4A (Week 1-2): Build managed services backend + Ahrefs + indexing
Phase 4B (Week 2-3): Build reporting engine + white-label + dashboards
Phase 4C (Week 3-4): Feature gating + WP.org submission + pricing update

Launch steps:
1. Enable `managed_services_enabled` feature flag in staging
2. Onboard 2-3 existing Alorig clients as beta managed service subscribers
3. Test full cycle: onboarding → content → backlinks → indexing → reporting
4. Fix issues from beta
5. Submit WP.org plugin (parallel with beta testing)
6. Enable feature flags in production
7. Update pricing page on marketing site
8. Send announcement email to existing users
9. Begin WP.org organic acquisition

**Existing User Migration:**

- Current users keep their existing plan (grandfathered)
- New feature gates apply to new features only — nothing existing breaks
- Migration script: populate `plan_features` JSONField on all existing Plan records
- Existing credits + billing unchanged

**3. Data Models & APIs:**

Modified models:

- `Plan` (billing app) — add field:
  - `plan_features` JSONField — feature capability matrix (see above)

New model:
- `FeatureUsageLog` (extends AccountBaseModel)
  - `feature` CharField — feature key checked
  - `required_level` CharField
  - `current_level` CharField
  - `was_allowed` BooleanField
  - `endpoint` CharField — API endpoint that triggered check
  - `timestamp` DateTimeField (auto_now_add)
  - Table: `igny8_feature_usage_log`
  - Purpose: track which features users hit gates on → inform pricing decisions

New endpoints:
```
# Feature Gates
GET    /api/v1/billing/features/                              # Current account's available features
GET    /api/v1/billing/features/check/{feature}/              # Check specific feature access

# Plan Management (admin)
GET    /api/v1/billing/plans/                                 # List all plans with features
PUT    /api/v1/billing/plans/{id}/features/                   # Update plan feature matrix

# Add-On Purchases
POST   /api/v1/billing/add-ons/managed-service/               # Purchase managed service
POST   /api/v1/billing/add-ons/backlink-package/              # Purchase backlink package
POST   /api/v1/billing/add-ons/indexing-boost/                # Purchase indexing credits
GET    /api/v1/billing/add-ons/                               # List available add-ons for current plan

# WP.org Plugin (public)
GET    /api/v1/plugins/igny8-seo/info/                        # Plugin info for WP update checker
GET    /api/v1/plugins/igny8-seo/download/                    # Download latest ZIP
GET    /api/v1/plugins/igny8-seo/check-update/                # Version check
```

Celery tasks:
- `migrate_plan_features` — one-time, populate plan_features on existing plans
- `sync_wporg_stats` — daily, fetch WP.org download/rating stats (if API available)
- `feature_usage_report` — weekly, aggregate FeatureUsageLog for product decisions

Services:
- `FeatureGateService` — check_feature(), get_plan_features(), log_usage()
- `AddOnPurchaseService` — process add-on purchases via existing Stripe/PayPal
- `WPOrgDeployService` — SVN deploy pipeline for WP.org (GitHub Actions config)

**Cross-references:** 04A (managed services pricing), 04B (reporting features gated by plan), All Phase 2 modules (each gated by plan level), 03A (WP.org plugin submission), existing billing app (Plan, Subscription models)

---

## BUILD SEQUENCE

```
Phase 4 Doc Build Order
═══════════════════════

1. 04A — Managed Services
   Foundation: subscription model, onboarding, Ahrefs, indexing
   (All other Phase 4 docs depend on this)

2. 04B — Whitelabel & Reporting
   Builds on 04A subscriptions + pulls data from Phase 2 modules

3. 04C — Pricing & Launch
   Wraps everything: feature gates across all modules, WP.org, go-to-market
   (Must be last — references all features from all phases)
```

For each doc:
1. Read this plan's section for that doc
2. Read the source files listed in "Source Material"
3. Read relevant Phase 2 docs for data model cross-references
4. Write the doc following the DOC STRUCTURE STANDARD
5. Verify all PKs are BigAutoField (integer, not UUID)
6. Verify all model names are PLURAL where applicable
7. Verify all frontend references use .tsx + Zustand
8. Save to `V2-Execution-Docs/04X-filename.md`

---

## SOURCE FILES TO READ

```
Live Docs on Server/igny8-app-docs/plans/final-dev-guides-of-futute-implementation/DocD-Business-Services-Dev-Guide.md
temp/IGNY8-Project-Files/IGNY8-Current-State.md
temp/IGNY8-Project-Files/SAG-Doc4-External-Backlink-Campaign-PLAN.md
V2-Execution-Docs/00-MASTER-EXECUTION-PLAN.md
V2-Execution-Docs/02C-gsc-integration.md (reporting data source)
V2-Execution-Docs/02E-linker-external-backlinks.md (campaign/backlink models)
V2-Execution-Docs/02H-socializer.md (social metrics for reports)
V2-Execution-Docs/01G-sag-health-monitoring.md (health score for reports)
```

---

*This document is the single instruction set for building all 3 Phase 4 execution documents. Each doc section above contains the complete spec needed to write a self-contained execution doc that Claude Code can pick up and build independently.*