igny8/docs/plans/final-dev-guides-of-futute-implementation/DocD-Business-Services-Dev-Guide.md

# Doc D — Business & Services: Development Guide for Claude Code

**Version:** 1.0
**Date:** March 2026
**For:** Claude Code (Opus 4.6) in VSCode on IGNY8 repo
**Purpose:** Implementation guide for the business/revenue layer — Managed Services Add-On, Backlink Service Tiers, client onboarding workflows, white-label reporting, and billing integration for services
**Scope:** Managed Add-On tiers (Lite $100, Pro $399/site/month), Backlink service packaging (self-service + managed), Alorig client portfolio servicing, billing models and margin tracking
**Rule:** Core IGNY8 SaaS subscription plans (Free/Starter/Growth/Scale) are unchanged. Managed services are add-ons purchased per site, layered on top of existing plans. All service delivery uses existing IGNY8 platform features — no separate tool stack.
**Dependency:** Doc A (SAG Architecture) provides blueprints and campaign generation. Doc B (Platform Modules) provides content pipeline, GSC, Socializer. Doc C (WordPress Ecosystem) provides plugin infrastructure for delivery.

---

## Table of Contents

1. [Business Context — Current Revenue Model](#1-business-context)
2. [Managed Services Add-On — Product Definition](#2-managed-addon)
3. [Backlink Services — Product Definition](#3-backlink-services)
4. [Implementation: Backend Models & Billing](#4-backend-models)
5. [Implementation: Frontend — Service Management UI](#5-frontend-ui)
6. [Implementation: Service Delivery Workflow](#6-delivery-workflow)
7. [Implementation: Client Onboarding Automation](#7-onboarding)
8. [Implementation: Reporting & White-Label](#8-reporting)
9. [Implementation: Alorig Client Portfolio Servicing](#9-alorig-portfolio)
10. [API Endpoints](#10-api-endpoints)
11. [Celery Tasks](#11-celery-tasks)
12. [Feature Flags](#12-feature-flags)
13. [Margin Tracking & Business Intelligence](#13-margin-tracking)

---

## 1. Business Context — Current Revenue Model {#1-business-context}

### 1.1 Existing Subscription Plans

| 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:** Stripe and PayPal integrated (pending production credentials). Manual payment methods available.

**Billing models:** `modules/billing/` (API layer), `business/billing/` (services). `CreditService` manages all credit operations. `Plan` model in `auth/models.py`.

### 1.2 Revenue Expansion Opportunities

The current model is pure SaaS subscription + credits. Two service layers add high-margin revenue without changing the core platform:

1. **Managed Services Add-On** — Alorig team operates the IGNY8 platform on behalf of clients. Client pays subscription + managed fee. Alorig does the work.
2. **Backlink Services** — Link building packages using FatGrid/PR distribution. Self-service (client buys intelligence, executes themselves) or managed (Alorig team executes).

Both use the existing platform. No separate tools needed. The "service" is human expertise + platform operation — not new software features.

### 1.3 Existing Infrastructure to Leverage

| What Exists | How Services Use It |
|-------------|-------------------|
| SAG Site Builder (Doc A Phase 4) | Managed: Alorig runs wizard for client. Self-service: client runs it themselves. |
| Content Pipeline (Doc B Modules 1-2) | Managed: Alorig configures and runs automation. Client gets published content. |
| Backlink Campaign Generator (Doc A Phase 10) | Both: Platform generates campaign plan. Managed: Alorig executes. Self-service: client executes. |
| GSC Integration (Doc B Module 4) | Managed: Alorig monitors indexing, submits URLs. Reports to client. |
| Socializer (Doc B Module 6) | Managed Pro: Alorig configures social posting for client. |
| Rich Schema (Doc B Module 5) | Managed: Alorig runs retroactive enhancement on client sites. |
| WordPress Plugin (Doc C) | Both: Plugin installed on client site. Managed: Alorig configures connected mode. |

---

## 2. Managed Services Add-On — Product Definition {#2-managed-addon}

### 2.1 Tiers

| Tier | Price | What Client Gets | What Alorig Does |
|------|-------|------------------|-----------------|
| **Managed Lite** | $100/site/month | 10 articles/month, basic SEO setup, monthly report | Run SAG wizard, configure automation for 10 articles, publish to WordPress, basic optimization, email monthly report |
| **Managed Pro** | $399/site/month | 30 articles/month, full SAG architecture, backlink campaign management, social posting, weekly report, dedicated account manager | Full SAG build, configure all automation stages, manage backlink campaign execution, configure socializer, run retroactive schema enhancement, weekly report with KPIs |

### 2.2 What's Included in Each Tier

**Managed Lite ($100/site/month):**
- Initial SAG blueprint generation (one-time, first month)
- 10 articles/month through the content pipeline
- Basic WordPress taxonomy setup from blueprint
- Content published to WordPress (auto or scheduled)
- Monthly PDF report: articles published, keywords tracked, basic traffic metrics
- Email support (48hr response)

**Managed Pro ($399/site/month):**
- Everything in Lite, plus:
- Full SAG architecture with detailed mode (not quick mode)
- 30 articles/month (hub pages + supporting content per blueprint execution priority)
- Taxonomy term content generation (term landing pages)
- Backlink campaign management: plan generation, link sourcing via FatGrid, quality verification, anchor text management
- Monthly backlink budget: separate from service fee, passed through at cost + 20% markup
- Social media content generation + scheduling across configured platforms
- Retroactive schema enhancement on existing site pages
- GSC monitoring: auto-indexing, re-inspection, issue alerts
- Weekly PDF report: content published, backlinks built, indexing status, keyword rankings, traffic, DR progress
- Dedicated Slack channel or email thread (24hr response)

### 2.3 Client Requirements

The client must provide or enable:
- WordPress admin access (or install IGNY8 plugin themselves)
- Domain/hosting (Alorig does not host client sites)
- Business data for SAG wizard (products/services, brands, locations, problems solved — per Doc A Section 9.3)
- Approval on SAG blueprint before execution (Alorig presents, client approves)
- Social media account access (for Managed Pro social posting)
- Backlink budget approval (for Managed Pro, separate from service fee)

### 2.4 Margin Analysis

| Component | Managed Lite | Managed Pro |
|-----------|-------------|-------------|
| Service fee | $100/month | $399/month |
| IGNY8 platform cost (credits) | ~$15-25/month (10 articles, basic images) | ~$50-80/month (30 articles, quality images, social, schema) |
| Human time (Alorig team) | ~2-3 hrs/month | ~8-12 hrs/month |
| Effective hourly rate | $25-40/hr | $25-35/hr |
| Gross margin | ~75% | ~70-80% (excluding backlink pass-through) |

Backlink costs are pass-through with 20% markup — not included in the service fee.

---

## 3. Backlink Services — Product Definition {#3-backlink-services}

### 3.1 Two Modes

**Self-Service Mode:**
Client uses IGNY8's backlink campaign module (Doc A Phase 10) to generate campaign plans, browse FatGrid publishers, and track links. IGNY8 provides the intelligence. Client executes link building themselves.

No additional subscription needed — included with Scale plan or as a credit-based add-on.

**Managed Mode:**
Client submits campaign to Alorig team. Alorig sources links, manages quality, tracks progress, generates white-label reports. Client pays per-link or monthly retainer.

### 3.2 Service Tiers (Managed Mode)

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

### 3.3 Monthly Packages (Managed Mode)

| Package | Links/Month | DR Range | Monthly Cost | Typical Site Size |
|---------|------------|----------|-------------|------------------|
| **Starter** | 5-8 links | DR 30-50 | $800-1,500 | Small sites, PK market |
| **Growth** | 10-15 links | DR 30-70 mix | $2,000-4,000 | Medium sites, UK/CA market |
| **Authority** | 15-25 links | DR 40-70+ mix + PR | $4,000-8,000 | Large sites, USA market |
| **Enterprise** | Custom | Custom | Custom | Multi-site, agency clients |

### 3.4 Niche Surcharges

| Niche | Multiplier | Reason |
|-------|-----------|--------|
| Crypto/Casino | 2-3x | Limited publishers, high competition |
| Finance/Insurance | 1.5-2x | YMYL, stricter publisher requirements |
| Health/Medical | 1.5-2x | YMYL, content quality requirements |
| Tech/SaaS | 1.2-1.5x | Moderate competition |
| General | 1x (baseline) | Standard pricing |

---

## 4. Implementation: Backend Models & Billing {#4-backend-models}

### 4.1 New Models

Add to existing billing module or create new services module:

```python
# modules/billing/models.py or new modules/services/models.py

class ManagedServiceSubscription(AccountBaseModel):
    """Managed service add-on subscription per site."""
    id = models.UUIDField(primary_key=True, default=uuid4)
    site = models.ForeignKey('auth.Site', on_delete=models.CASCADE, related_name='managed_subscriptions')
    tier = models.CharField(max_length=20, choices=[
        ('lite', 'Managed Lite'),
        ('pro', 'Managed Pro'),
    ])
    status = models.CharField(max_length=20, choices=[
        ('pending', 'Pending Setup'),
        ('active', 'Active'),
        ('paused', 'Paused'),
        ('cancelled', 'Cancelled'),
    ], default='pending')
    monthly_price = models.DecimalField(max_digits=8, decimal_places=2)
    articles_per_month = models.IntegerField()
    
    # Assigned team member
    account_manager = models.ForeignKey('auth.User', null=True, blank=True, on_delete=models.SET_NULL,
        related_name='managed_clients')
    
    # Tracking
    current_month_articles_published = models.IntegerField(default=0)
    current_month_start = models.DateField(null=True, blank=True)
    
    # Service config
    service_config = models.JSONField(default=dict, help_text='Per-site service configuration: automation settings, social platforms, backlink budget, report schedule')
    
    started_at = models.DateTimeField(null=True, blank=True)
    cancelled_at = models.DateTimeField(null=True, blank=True)
    next_billing_date = models.DateField(null=True, blank=True)

class BacklinkServiceOrder(AccountBaseModel):
    """Individual backlink service order or monthly retainer."""
    id = models.UUIDField(primary_key=True, default=uuid4)
    site = models.ForeignKey('auth.Site', on_delete=models.CASCADE)
    campaign = models.ForeignKey('sag.SAGCampaign', null=True, blank=True, on_delete=models.SET_NULL)
    
    order_type = models.CharField(max_length=20, choices=[
        ('one_time', 'One-Time Order'),
        ('monthly', 'Monthly Retainer'),
    ])
    package = models.CharField(max_length=30, choices=[
        ('starter', 'Starter (5-8 links)'),
        ('growth', 'Growth (10-15 links)'),
        ('authority', 'Authority (15-25 links)'),
        ('enterprise', 'Enterprise (custom)'),
        ('custom', 'Custom Order'),
    ], blank=True)
    
    # Financial
    client_price = models.DecimalField(max_digits=10, decimal_places=2)
    actual_cost = models.DecimalField(max_digits=10, decimal_places=2, default=0)
    margin = models.DecimalField(max_digits=10, decimal_places=2, default=0)
    niche_surcharge = models.FloatField(default=1.0, help_text='Multiplier: 1.0 = baseline')
    
    # Delivery
    links_ordered = models.IntegerField(default=0)
    links_delivered = models.IntegerField(default=0)
    links_live = models.IntegerField(default=0)
    
    status = models.CharField(max_length=20, choices=[
        ('draft', 'Draft'),
        ('approved', 'Approved'),
        ('in_progress', 'In Progress'),
        ('delivered', 'Delivered'),
        ('completed', 'Completed'),
    ], default='draft')
    
    # Tracking
    ordered_at = models.DateTimeField(null=True, blank=True)
    delivered_at = models.DateTimeField(null=True, blank=True)
    notes = models.TextField(blank=True)

class ServiceReport(AccountBaseModel):
    """Generated report for a managed service client."""
    id = models.UUIDField(primary_key=True, default=uuid4)
    site = models.ForeignKey('auth.Site', on_delete=models.CASCADE)
    managed_subscription = models.ForeignKey(ManagedServiceSubscription, null=True, blank=True, on_delete=models.SET_NULL)
    
    report_type = models.CharField(max_length=20, choices=[
        ('weekly', 'Weekly Report'),
        ('monthly', 'Monthly Report'),
        ('quarterly', 'Quarterly Review'),
    ])
    period_start = models.DateField()
    period_end = models.DateField()
    
    # Report data
    report_data = models.JSONField(default=dict, help_text='All metrics for this period')
    report_pdf_url = models.URLField(blank=True, help_text='Generated PDF stored in S3')
    
    # White-label
    is_white_label = models.BooleanField(default=False)
    brand_name = models.CharField(max_length=200, blank=True, help_text='Client-facing brand name (if white-label)')
    brand_logo_url = models.URLField(blank=True)
    
    generated_at = models.DateTimeField(auto_now_add=True)
    sent_at = models.DateTimeField(null=True, blank=True)
```

### 4.2 Billing Integration

Managed services integrate with the existing billing system:

```python
# business/billing/managed_billing_service.py    # NEW

class ManagedBillingService:
    def create_managed_subscription(self, site, tier, payment_method):
        """Create managed service subscription + first invoice."""
        # 1. Create ManagedServiceSubscription record
        # 2. Create Stripe/PayPal subscription or manual invoice
        # 3. Deduct from account credit balance OR charge directly
        # 4. Set next_billing_date
        pass
    
    def process_monthly_billing(self):
        """Celery task: process all active managed subscriptions monthly."""
        # For each active subscription:
        # 1. Generate invoice
        # 2. Charge payment method
        # 3. Reset current_month_articles_published
        # 4. Update current_month_start
        pass
    
    def process_backlink_order(self, order):
        """Process payment for a backlink service order."""
        # 1. Calculate total: client_price × niche_surcharge
        # 2. Charge payment method
        # 3. Update order status to 'approved'
        pass
    
    def calculate_margin(self, order):
        """Calculate and store margin on a completed backlink order."""
        order.margin = order.client_price - order.actual_cost
        order.save()
```

### 4.3 Service Configuration Storage

The `service_config` JSON field on ManagedServiceSubscription stores per-client settings:

```json
{
  "automation": {
    "schedule": "weekly",
    "articles_per_run": 3,
    "content_types": ["post", "cluster_hub", "taxonomy_landing"],
    "auto_publish": false,
    "review_required": true
  },
  "backlinks": {
    "monthly_budget": 2000,
    "target_country": "US",
    "package": "growth",
    "auto_approve_under": 200
  },
  "social": {
    "platforms": ["linkedin", "twitter"],
    "auto_post_on_publish": true,
    "posting_schedule": "best_time"
  },
  "reporting": {
    "frequency": "weekly",
    "format": "pdf",
    "white_label": false,
    "recipients": ["client@example.com"],
    "include_backlinks": true,
    "include_rankings": true,
    "include_traffic": true
  }
}
```

---

## 5. Implementation: Frontend — Service Management UI {#5-frontend-ui}

### 5.1 Admin-Only Service Dashboard

This is an internal Alorig team interface, not client-facing.

```
frontend/src/pages/
└── Services/                          # NEW page (admin only)
    ├── ServicesDashboard.tsx          # Overview: all managed clients, revenue summary
    │   ├── ClientList.tsx             # All managed subscriptions with status
    │   ├── RevenueSummary.tsx         # MRR, active clients, margin totals
    │   └── UpcomingActions.tsx        # Tasks due: reports, renewals, content due
    ├── ClientDetail.tsx               # Single client management view
    │   ├── ClientConfig.tsx           # Service config editor (automation, social, backlinks)
    │   ├── ContentTracker.tsx         # Articles published this month vs target
    │   ├── BacklinkTracker.tsx        # Links ordered vs delivered vs live
    │   ├── ReportHistory.tsx          # Generated reports with resend option
    │   └── BillingHistory.tsx         # Invoices, payments, margin
    ├── BacklinkOrders.tsx             # All backlink orders across clients
    │   ├── OrderList.tsx              # Filterable by client, status, package
    │   └── OrderDetail.tsx            # Individual order with link-by-link tracking
    └── ReportGenerator.tsx            # Generate reports for any client/period
```

**Sidebar addition (admin only):**
```
ADMIN
  ├── Sector Templates
  └── Managed Services (NEW — admin only)
```

### 5.2 Client-Facing View (Optional)

Managed clients who also have IGNY8 app access see a simplified view:

```
frontend/src/pages/
└── ManagedService/                    # NEW page (for managed clients)
    ├── ServiceOverview.tsx            # What's included, current month progress
    ├── ReportViewer.tsx               # View past reports
    └── ApprovalQueue.tsx              # Approve blueprint, content (if review_required)
```

This page appears in the client's sidebar only if they have an active `ManagedServiceSubscription`:
```
ACCOUNT
  ├── Account Settings
  ├── Plans & Billing
  ├── Managed Service (NEW — if managed subscription active)
  ├── Usage
  └── AI Models
```

---

## 6. Implementation: Service Delivery Workflow {#6-delivery-workflow}

### 6.1 Managed Lite — Monthly Workflow

```
Month Start
  │
  ├── Check: blueprint exists? If not → run SAG wizard for client (first month)
  │
  ├── Run automation pipeline (10 articles):
  │   1. Blueprint check → load unfulfilled content needs
  │   2. Generate ideas from blueprint (execution priority order)
  │   3. Create tasks (content_type based on blueprint)
  │   4. Generate content (type-specific prompts)
  │   5. Generate images
  │   6. → Review queue
  │
  ├── Alorig team reviews content (manual quality check)
  │   - Approve or edit in Writer → Review tab
  │   - Publish approved content to WordPress
  │
  ├── Update ManagedServiceSubscription.current_month_articles_published
  │
  └── Month End:
      ├── Generate monthly report (ServiceReport)
      ├── Send to client via email
      └── Process next month billing
```

### 6.2 Managed Pro — Monthly Workflow

```
Month Start
  │
  ├── Everything from Lite, PLUS:
  │
  ├── Run automation for 30 articles (hub pages prioritized in early months)
  │
  ├── Backlink campaign management:
  │   1. Load this month's plan from SAGCampaign
  │   2. Browse FatGrid for publishers matching plan criteria
  │   3. Place orders on FatGrid/PR platforms
  │   4. Track delivery: ordered → pending → live
  │   5. Quality check each delivered link
  │   6. Log in SAGBacklink records
  │   7. Run dead link check on previous links
  │
  ├── Social media:
  │   1. Generate social posts for published content
  │   2. Schedule across configured platforms
  │   3. Monitor engagement metrics
  │
  ├── Schema enhancement:
  │   1. Run retroactive schema scan on any new/updated pages
  │   2. Generate and push schemas to WordPress
  │
  ├── GSC monitoring:
  │   1. Check indexing status of all published content
  │   2. Re-request indexing for pending items
  │   3. Flag issues to client if needed
  │
  └── Week End (weekly report):
      ├── Generate weekly report (ServiceReport)
      ├── Include: articles published, backlinks built, indexing status, ranking changes
      └── Send to client
```

### 6.3 Backlink Order Workflow (Managed Mode)

```
Client approves monthly backlink budget
  │
  ├── Alorig loads this month's campaign plan from IGNY8
  │   - Target pages, DR ranges, anchor text mix, link count
  │
  ├── Browse FatGrid publishers:
  │   - Filter by: country, niche, DR range, budget
  │   - Compare prices across marketplaces
  │   - Select best-value publishers
  │
  ├── Place orders:
  │   - Guest post orders on FatGrid
  │   - PR distribution on EIN Presswire / PRNews.io
  │   - Create BacklinkServiceOrder record
  │
  ├── Track delivery:
  │   - Monitor publisher for content creation
  │   - Verify link is live (HTTP check)
  │   - Quality check: DR, traffic, niche relevance, outbound links
  │   - Log each link as SAGBacklink
  │
  ├── Quality scoring:
  │   - Auto-score where possible (Ahrefs/FatGrid data)
  │   - Manual checks: content quality, relevance, link placement
  │   - Flag issues if quality below threshold
  │
  └── Update campaign:
      - BacklinkServiceOrder.links_delivered++
      - SAGCampaign KPI update
      - Calculate margin: client_price - actual_cost
```

---

## 7. Implementation: Client Onboarding Automation {#7-onboarding}

### 7.1 Managed Client Onboarding Flow

When a managed service subscription is created:

```python
# business/services/onboarding_service.py    # NEW

class ManagedOnboardingService:
    def onboard_client(self, subscription):
        """Automated onboarding for new managed client."""
        site = subscription.site
        
        # Step 1: Ensure IGNY8 plugin is installed and connected
        # Check site.wp_api_key exists → if not, send installation guide email
        
        # Step 2: Run SAG Site Builder if no blueprint exists
        if not site.sag_blueprint_id:
            # Queue Celery task to generate blueprint
            # Notification to account manager: "Blueprint ready for review"
            pass
        
        # Step 3: Configure automation based on service_config
        # Set AutomationConfig schedule, stages, content types
        
        # Step 4: Send welcome email to client
        # Include: what to expect, how to approve content, contact info
        
        # Step 5: Create first month tasks in internal queue
        # Notification to account manager: "New client onboarded, first content due"
        
        # Step 6: Update subscription status: pending → active
```

### 7.2 Client Intake Form

For collecting business data (feeds into SAG wizard):

```
frontend/src/pages/Services/
└── components/
    └── ClientIntakeForm.tsx    # NEW — admin fills this during client onboarding
```

Collects per Doc A Section 9.3:
- Site URL, industry, sectors
- Products/services list
- Problems solved
- Brands (if e-commerce)
- Locations (if service-based)
- Competitors
- Target countries (for backlink campaigns)
- Social media accounts
- Current SEO status (any existing plugins, backlink profile)

This data feeds directly into the SAG wizard's business data inputs.

---

## 8. Implementation: Reporting & White-Label {#8-reporting}

### 8.1 Report Generation Service

```python
# business/services/report_service.py    # NEW

class ReportService:
    def generate_report(self, site, period_start, period_end, report_type, white_label=False):
        """Generate a service report for a managed client."""
        report_data = {
            'content': self._get_content_metrics(site, period_start, period_end),
            'backlinks': self._get_backlink_metrics(site, period_start, period_end),
            'indexing': self._get_indexing_metrics(site, period_start, period_end),
            'rankings': self._get_ranking_metrics(site, period_start, period_end),
            'traffic': self._get_traffic_metrics(site, period_start, period_end),
            'social': self._get_social_metrics(site, period_start, period_end),
            'health': self._get_sag_health(site),
        }
        
        # Generate PDF
        pdf_url = self._render_pdf(report_data, white_label, site)
        
        # Create ServiceReport record
        report = ServiceReport.objects.create(
            site=site, report_type=report_type,
            period_start=period_start, period_end=period_end,
            report_data=report_data, report_pdf_url=pdf_url,
            is_white_label=white_label,
        )
        return report
    
    def _get_content_metrics(self, site, start, end):
        """Articles published, content types breakdown, word count total."""
        pass
    
    def _get_backlink_metrics(self, site, start, end):
        """Links built, DR distribution, cost, quality scores."""
        pass
    
    def _get_indexing_metrics(self, site, start, end):
        """Pages indexed, pending, errors (from GSC module)."""
        pass
    
    def _get_ranking_metrics(self, site, start, end):
        """Keywords in top 10/20/50, position changes (from GSC module)."""
        pass
    
    def _get_traffic_metrics(self, site, start, end):
        """Organic traffic, impressions, CTR (from GSC module)."""
        pass
    
    def _get_social_metrics(self, site, start, end):
        """Posts published, engagement, clicks (from Socializer module)."""
        pass
    
    def _get_sag_health(self, site):
        """SAG health score, cluster completion (from SAG module)."""
        pass
```

### 8.2 PDF Report Template

Reports generated as PDF using a template system. Stored in S3/media storage.

**Report sections (configurable per client):**
1. Executive Summary — key wins this period
2. Content Performance — articles published, type breakdown
3. Indexing Status — indexed/pending/error counts with trend
4. Keyword Rankings — top movers, new entries, lost positions
5. Organic Traffic — clicks, impressions, CTR with month-over-month
6. Backlink Campaign (if active) — links built, DR distribution, budget spent, quality
7. Social Media (if active) — posts, engagement, top performers
8. SAG Health — overall score, cluster completion, recommendations
9. Next Month Plan — what's coming, what client needs to approve

### 8.3 White-Label Support

For agency clients reselling IGNY8 services:
- `ServiceReport.brand_name` replaces "IGNY8" / "Alorig" throughout PDF
- `ServiceReport.brand_logo_url` replaces logo in PDF header
- Report footer shows agency contact info, not Alorig
- White-label reports generated via Linking News API for backlink reporting

---

## 9. Implementation: Alorig Client Portfolio Servicing {#9-alorig-portfolio}

### 9.1 Current Alorig Clients (from Rich Schema doc)

| Client | Type | Site | Priority Services |
|--------|------|------|------------------|
| Banner Printing (UK) | Service/eCommerce | ~50 pages | FAQ Schema, Breadcrumbs, Local Business Schema, Review markup |
| Aterna Advisors (CA) | Finance content | ~135 pages | Article + Author Schema (YMYL), FAQ, TL;DR, Definition blocks |
| Seva Mattress | WooCommerce | Product catalog | Product Schema, AggregateRating, FAQ, Pros & Cons |
| VAINO | WooCommerce + brand | Product + brand pages | Product Schema, Breadcrumbs, FAQ, Review markup |
| African Fair Trade Society | Nonprofit content | Content + service pages | Article Schema, FAQ, Organization Schema, Breadcrumbs |
| Halal VPN | Blog + product | Blog + product pages | Article, HowTo, FAQ, Comparison Tables, Pros & Cons |

### 9.2 Per-Client Service Plan

Each Alorig client can be onboarded as a Managed Service subscriber:

```
For each client:
  1. Create ManagedServiceSubscription (Lite or Pro based on scope)
  2. Run client intake → collect business data
  3. Run SAG Site Builder → generate blueprint
  4. Install/update IGNY8 plugin on client site
  5. Run retroactive schema enhancement (Rich Schema module)
  6. Configure content pipeline based on gaps
  7. Set up reporting schedule
  8. (Pro clients) Generate backlink campaign, begin execution
```

### 9.3 Internal Service Tracking

The admin Services Dashboard provides at-a-glance view of all Alorig clients:
- Client name, site, tier, status
- This month: articles target vs published, backlinks target vs delivered
- Overdue items: reports not sent, content not published, links behind schedule
- Revenue: MRR from managed services, backlink revenue, total margin

---

## 10. API Endpoints {#10-api-endpoints}

### Managed Services

```
GET    /api/v1/services/subscriptions/                    # List managed subscriptions (admin)
POST   /api/v1/services/subscriptions/                    # Create subscription
GET    /api/v1/services/subscriptions/{id}/               # Subscription detail
PATCH  /api/v1/services/subscriptions/{id}/               # Update config, status
POST   /api/v1/services/subscriptions/{id}/onboard/       # Trigger onboarding workflow
POST   /api/v1/services/subscriptions/{id}/pause/         # Pause subscription
POST   /api/v1/services/subscriptions/{id}/cancel/        # Cancel subscription
```

### Backlink Orders

```
GET    /api/v1/services/backlink-orders/                  # List orders (admin)
POST   /api/v1/services/backlink-orders/                  # Create order
GET    /api/v1/services/backlink-orders/{id}/             # Order detail
PATCH  /api/v1/services/backlink-orders/{id}/             # Update status, delivery
GET    /api/v1/services/backlink-orders/{id}/links/       # Links in this order
```

### Reports

```
GET    /api/v1/services/reports/                          # List reports (admin + client)
POST   /api/v1/services/reports/generate/                 # Generate report
GET    /api/v1/services/reports/{id}/                     # Report detail + PDF URL
POST   /api/v1/services/reports/{id}/send/                # Email report to client
```

### Dashboard (Admin)

```
GET    /api/v1/services/dashboard/                        # Revenue summary, client overview
GET    /api/v1/services/dashboard/overdue/                # Overdue tasks across clients
GET    /api/v1/services/dashboard/margin/                 # Margin tracking summary
```

---

## 11. Celery Tasks {#11-celery-tasks}

| Task | Schedule | Purpose |
|------|----------|---------|
| `process_managed_billing` | Monthly (1st of month) | Invoice all active managed subscriptions |
| `generate_weekly_reports` | Weekly (Monday 6am) | Generate reports for all Pro clients |
| `generate_monthly_reports` | Monthly (1st of month) | Generate reports for all Lite + Pro clients |
| `send_pending_reports` | Daily | Email any generated but unsent reports |
| `check_overdue_deliverables` | Daily | Flag any managed clients behind on content/links |
| `reset_monthly_counters` | Monthly (1st of month) | Reset current_month_articles_published |
| `check_backlink_delivery` | Daily | Check FatGrid/publisher status on open orders |

---

## 12. Feature Flags {#12-feature-flags}

| Flag | Controls | Default |
|------|---------|---------|
| `managed_services_enabled` | Services admin page, subscription management, onboarding | `False` |
| `backlink_orders_enabled` | Backlink order management (independent of campaign module) | `False` |
| `white_label_reports` | White-label branding on reports | `False` |

---

## 13. Margin Tracking & Business Intelligence {#13-margin-tracking}

### 13.1 What to Track

| Metric | Source | Aggregation |
|--------|--------|-------------|
| Managed Services MRR | Sum of active ManagedServiceSubscription.monthly_price | Monthly |
| Backlink Revenue | Sum of BacklinkServiceOrder.client_price (completed orders) | Monthly |
| Backlink Cost | Sum of BacklinkServiceOrder.actual_cost | Monthly |
| Backlink Margin | Revenue - Cost per order, aggregated | Monthly |
| Blended Margin % | (Total Revenue - Total Cost) / Total Revenue | Monthly |
| Cost Per Article | Platform credits used / articles published per client | Monthly |
| Team Hours (manual tracking) | Time spent per client | Monthly |
| Effective Hourly Rate | (Revenue - Platform Costs) / Hours | Monthly |
| Client Retention | Active subscriptions / Total ever created | Lifetime |
| Average Revenue Per Client | Total revenue / Active clients | Monthly |

### 13.2 Admin Dashboard Metrics

The Services Dashboard (admin-only) shows:
- Total MRR from managed services
- Total backlink revenue (monthly)
- Blended margin percentage
- Client count by tier (Lite vs Pro)
- Top 5 clients by revenue
- Clients behind on deliverables
- Month-over-month growth

### 13.3 Future: Automated Margin Calculation

When FatGrid API integration is complete (Doc A Phase 10), backlink order costs can be auto-populated from actual FatGrid transaction data, making margin tracking fully automated instead of manually entered.

---

## Reference Documents

| Document | Purpose |
|----------|---------|
| **IGNY8-Current-State.md** | Billing system, credit costs, subscription plans |
| **SAG-Doc4-External-Backlink-Campaign-PLAN.md** | Campaign generation, FatGrid tiers, service pricing |
| **IGNY8-Rich-Schema-SERP-Enhancement-Module.docx** | Client portfolio with retroactive enhancement opportunities |
| **Doc A — SAG Architecture Dev Guide** | Campaign module (Phase 10), SAG Site Builder (Phase 4) |
| **Doc B — Platform Modules Dev Guide** | GSC, Socializer, Rich Schema — features delivered to managed clients |
| **Doc C — WordPress Ecosystem Dev Guide** | Plugin installation and configuration for managed sites |

---

*End of Doc D — Business & Services Development Guide*