# IGNY8 Phase 4: Managed Services (04A)
## Service Tiers, Backlink Orders, Ahrefs Integration, Backlink Indexing

**Document Version:** 1.0
**Date:** 2026-03-23
**Phase:** IGNY8 Phase 4 — Business Layer
**Status:** Build Ready
**Source of Truth:** Codebase at `/data/app/igny8/`
**Audience:** Claude Code, Backend Developers, Business Operations, Architects

---

## 1. CURRENT STATE

### Billing Infrastructure Exists
The billing app provides:
- `Plan` — subscription tier definition (Free/$49/$149/$349)
- `Subscription` — active subscription per account, links to Plan
- `CreditTransaction` — credit debit/credit events
- `CreditUsageLog` — per-operation usage tracking
- `CreditCostConfig` — configurable cost per operation type (PK = operation_type)
- `AccountPaymentMethod` — saved Stripe/PayPal payment methods
- `Payment` + `Invoice` — payment and invoice records
- `CreditService` in `business/billing/` — pattern: `check_credits()` → execute → `deduct_credits()` → `log_usage()`
- Stripe + PayPal live and integrated

### Current Plans

| Plan | Price | Sites | Users | Credits/Mo |
|------|-------|-------|-------|------------|
| Free | $0 | 1 | 1 | 100 |
| Starter | $49 | 3 | 3 | 1,000 |
| Growth | $149 | 10 | 10 | 5,000 |
| Scale | $349 | Unlimited | Unlimited | 25,000 |

### What Does NOT Exist
- No managed services layer — Alorig manages client sites manually
- No backlink order tracking — orders placed manually on FatGrid/PRNews
- No Ahrefs integration — domain/backlink data checked manually
- No backlink indexing service — links indexed organically or manually submitted
- No automated onboarding — each client setup is manual
- 6 existing Alorig clients ready for managed service conversion

### Phase 2 Models Available
- `SAGCampaign`, `SAGBacklink`, `CampaignKPISnapshot` (02E) — backlink campaign engine
- `GSCConnection`, `URLInspectionRecord`, `GSCMetricsCache` (02C) — GSC data
- `SAGLink`, `SAGLinkAudit`, `LinkMap` (02D) — internal linking
- `SocialPost`, `SocialAccount`, `SocialEngagement` (02H) — socializer
- `SchemaTemplate`, `SERPEnhancement`, `SchemaValidationResult` (02G) — schema
- `AutomationConfig`, `AutomationRun` (automation app) — pipeline orchestration
- All IDs are integers (BigAutoField)

---

## 2. WHAT TO BUILD

### Overview
A managed services layer that lets Alorig sell done-for-you SEO services at two tiers, with integrated backlink ordering, Ahrefs API monitoring, and backlink indexing. Everything builds on existing IGNY8 models and infrastructure.

### 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

**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 (EIN Presswire) | $99-499 | $500-1,500 | 3-5× |
| PR Premium | Yahoo/Bloomberg/Fox | $500-5,000 | $2,000-15,000 | 3-4× |

**Monthly Retainer Packages:**
| Package | Links/Mo | DR Range | Monthly Cost | Market |
|---------|----------|----------|-------------|--------|
| Starter | 5-8 | DR 30-50 | $800-1,500 | PK |
| Growth | 10-15 | DR 30-70 mix | $2,000-4,000 | UK/CA |
| Authority | 15-25 | DR 40-70+ mix + PR | $4,000-8,000 | USA |
| 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

IGNY8 integrates with Ahrefs API v3 for automated domain metrics and backlink monitoring.

**API Endpoints Used:**
| Ahrefs Endpoint | IGNY8 Use Case |
|-----------------|----------------|
| `GET /v3/site-explorer/domain-rating` | DR for any domain (backlink quality scoring) |
| `GET /v3/site-explorer/backlinks` | Verify placed backlinks are live |
| `GET /v3/site-explorer/referring-domains` | Referring domain list + metrics |
| `GET /v3/site-explorer/organic-keywords` | Keyword rankings (supplement GSC data) |
| `GET /v3/site-explorer/pages-by-traffic` | Top pages by organic traffic |
| `GET /v3/site-explorer/metrics` | Domain summary (DR, referring domains, traffic, keywords) |
| `GET /v3/site-explorer/metrics-history` | Historical DR + traffic trend |
| `GET /v3/site-explorer/refdomains-history` | Referring domains over time |

**Use Cases:**
1. **Backlink verification** — after SAGBacklink placed, verify via Ahrefs crawl data
2. **Quality scoring** — auto-populate `source_dr`, `source_traffic` on SAGBacklink
3. **Campaign KPIs** — pull DR, referring domains, keywords for CampaignKPISnapshot
4. **Competitor analysis** — compare client's metrics against competitors
5. **Dead link detection** — cross-reference lost backlinks with SAGBacklink records
6. **Reporting** — feed ServiceReport data (04B)
7. **Link prospecting** — find competitor backlinks for outreach

**Pricing:** Credits-based (varies by Ahrefs plan). API key stored per account in `AhrefsConnection`.

### Backlink Indexing Service

After a backlink is placed and verified live, submit it for Google indexing to accelerate authority transfer.

**Indexing Services (integrate best available):**
- IndexNow API (free) — Bing/Yandex submission
- SpeedyIndex — fast indexing, API available, credit-based
- Omega Indexer — bulk indexing, ~$0.02-0.05/URL

**Integration Flow:**
```
SAGBacklink.status → 'live'
  → Verify URL accessible (HTTP 200)
  → Queue BacklinkIndexingRequest (status: queued)
  → Submit via indexing service API (status: submitted)
  → Wait 7 days, check if indexed
  → If indexed → is_indexed = True, status → indexed
  → If not after 14 days → re-submit once (status: resubmitted)
  → If still not after 28 days → status → failed, flag for review
```

**Client Pricing:** $0.10-0.20 per URL (5-10× markup); included in Managed Pro tier.

### Client Onboarding Automation

When `ManagedServiceSubscription` is created:
1. Verify site has IGNY8 plugin installed + connected (`SiteIntegration` exists)
2. If no blueprint → queue Celery task to auto-generate SAG blueprint
3. Configure `AutomationConfig` based on `service_config` (schedule, stages, content types)
4. Send welcome email (expectations, content approval process, contact info)
5. Create first month's 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 → Verify blueprint → 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 — extends Lite):**
```
+ Run pipeline for 30 articles (hubs prioritized)
+ Taxonomy term content generation
+ Backlink: Load SAGCampaign plan → Browse FatGrid → Place orders →
  Track delivery → Quality check → Log SAGBacklink → Submit for indexing
+ Social: Generate adapted posts → Schedule via best-time algorithm
+ Schema: Retroactive scan → Push to WP
+ GSC: Check indexing → Re-request pending → Flag issues
+ Weekly: Generate report → Send
```

### 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%** |

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

---

## 3. DATA MODELS & APIS

### New App: `services`

**App Label:** `services`
**Location:** `igny8_core/services/`
**Table Prefix:** `igny8_`

### New Models

**`ManagedServiceSubscription`** (extends `AccountBaseModel`)
| Field | Type | Description |
|-------|------|-------------|
| `site` | ForeignKey(Site) | Which site is being managed |
| `tier` | CharField(max_length=20) | `lite` / `pro` |
| `status` | CharField(max_length=20) | `pending` / `active` / `paused` / `cancelled` |
| `monthly_price` | DecimalField(8,2) | Monthly fee |
| `articles_per_month` | IntegerField | Target articles per month |
| `account_manager` | ForeignKey(User, null=True) | Assigned team member |
| `current_month_articles_published` | IntegerField(default=0) | Counter |
| `current_month_start` | DateField(null=True) | Current billing period start |
| `service_config` | JSONField | Per-site settings (automation, social, backlinks, reporting) |
| `started_at` | DateTimeField(null=True) | Service start timestamp |
| `cancelled_at` | DateTimeField(null=True) | Cancellation timestamp |
| `next_billing_date` | DateField(null=True) | Next billing date |

Table: `igny8_managed_service_subscriptions`

**`BacklinkServiceOrder`** (extends `AccountBaseModel`)
| Field | Type | Description |
|-------|------|-------------|
| `site` | ForeignKey(Site) | Target site |
| `campaign` | ForeignKey(SAGCampaign, null=True) | Linked campaign from 02E |
| `managed_subscription` | ForeignKey(ManagedServiceSubscription, null=True) | If part of managed service |
| `order_type` | CharField(max_length=20) | `one_time` / `monthly` |
| `package` | CharField(max_length=50) | `starter` / `growth` / `authority` / `enterprise` / `custom` |
| `client_price` | DecimalField(10,2) | Price charged to client |
| `actual_cost` | DecimalField(10,2, default=0) | Actual cost to Alorig |
| `margin` | DecimalField(10,2, default=0) | Calculated margin |
| `niche_surcharge` | FloatField(default=1.0) | Niche multiplier |
| `links_ordered` | IntegerField(default=0) | Total links ordered |
| `links_delivered` | IntegerField(default=0) | Links delivered by vendor |
| `links_live` | IntegerField(default=0) | Confirmed live |
| `links_indexed` | IntegerField(default=0) | Confirmed indexed |
| `status` | CharField(max_length=20) | `draft` / `approved` / `in_progress` / `delivered` / `completed` |
| `ordered_at` | DateTimeField(null=True) | Order placement date |
| `delivered_at` | DateTimeField(null=True) | Full delivery date |
| `notes` | TextField(blank=True) | Internal notes |

Table: `igny8_backlink_service_orders`

**`AhrefsConnection`** (extends `AccountBaseModel`)
| Field | Type | Description |
|-------|------|-------------|
| `api_key` | TextField | Encrypted Ahrefs API key |
| `plan_type` | CharField(null=True) | `lite` / `standard` / `advanced` / `enterprise` |
| `credits_remaining` | IntegerField(null=True) | Remaining API credits |
| `last_synced` | DateTimeField(null=True) | Last sync timestamp |
| `status` | CharField(max_length=20) | `active` / `expired` / `error` |

Table: `igny8_ahrefs_connections`

**`AhrefsDomainSnapshot`** (extends `SiteSectorBaseModel`)
| Field | Type | Description |
|-------|------|-------------|
| `domain` | CharField(max_length=255) | Domain name |
| `domain_rating` | FloatField | DR score |
| `referring_domains` | IntegerField | Count |
| `organic_keywords` | IntegerField | Count |
| `organic_traffic` | IntegerField | Estimated monthly |
| `backlinks_total` | IntegerField | Total backlinks |
| `snapshot_date` | DateField | Date of snapshot |
| `raw_data` | JSONField | Full API response |

Table: `igny8_ahrefs_domain_snapshots`

**`BacklinkIndexingRequest`** (extends `SiteSectorBaseModel`)
| Field | Type | Description |
|-------|------|-------------|
| `backlink` | ForeignKey(SAGBacklink) | Linked backlink from 02E |
| `url` | URLField | Source URL to be indexed |
| `indexing_service` | CharField(max_length=30) | `speedyindex` / `omega` / `colossus` / `indexnow` / `manual` |
| `service_request_id` | CharField(null=True) | External service reference |
| `submitted_at` | DateTimeField(null=True) | Submission timestamp |
| `first_check_at` | DateTimeField(null=True) | First index check |
| `last_check_at` | DateTimeField(null=True) | Last index check |
| `check_count` | IntegerField(default=0) | Times checked |
| `is_indexed` | BooleanField(default=False) | Is indexed |
| `indexed_at` | DateTimeField(null=True) | When indexed |
| `status` | CharField(max_length=20) | `queued` / `submitted` / `checking` / `indexed` / `failed` / `resubmitted` |
| `cost` | DecimalField(6,4, default=0) | Cost per submission |

Table: `igny8_backlink_indexing_requests`

### Modified Models

**`SAGBacklink`** (from 02E linker app) — add fields:
| Field | Type | Description |
|-------|------|-------------|
| `is_indexed` | BooleanField(default=False) | Indexed in Google |
| `indexed_at` | DateTimeField(null=True) | When indexed |
| `ahrefs_verified` | BooleanField(default=False) | Verified via Ahrefs |
| `ahrefs_last_seen` | DateTimeField(null=True) | Last seen in Ahrefs |
| `indexing_submitted` | BooleanField(default=False) | Submitted for indexing |

### API Endpoints

All under `/api/v1/`:

**Managed Service Subscriptions:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/services/subscriptions/` | List all (admin only) |
| POST | `/services/subscriptions/` | Create subscription |
| GET | `/services/subscriptions/{id}/` | Detail |
| PATCH | `/services/subscriptions/{id}/` | Update config/status |
| POST | `/services/subscriptions/{id}/onboard/` | Trigger onboarding flow |
| POST | `/services/subscriptions/{id}/pause/` | Pause service |
| POST | `/services/subscriptions/{id}/resume/` | Resume service |
| POST | `/services/subscriptions/{id}/cancel/` | Cancel service |

**Backlink Service Orders:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/services/backlink-orders/` | List all (admin) |
| POST | `/services/backlink-orders/` | Create order |
| GET | `/services/backlink-orders/{id}/` | Detail |
| PATCH | `/services/backlink-orders/{id}/` | Update status |
| GET | `/services/backlink-orders/{id}/links/` | Links in order |
| POST | `/services/backlink-orders/{id}/approve/` | Client approval |

**Ahrefs Integration:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/integration/ahrefs/connect/` | Save API key |
| DELETE | `/integration/ahrefs/disconnect/` | Remove connection |
| GET | `/integration/ahrefs/status/` | Connection status + credits |
| GET | `/integration/ahrefs/domain/{domain}/` | Domain metrics |
| GET | `/integration/ahrefs/domain/{domain}/history/` | DR + traffic history |
| GET | `/integration/ahrefs/backlinks/{domain}/` | Backlinks list |
| GET | `/integration/ahrefs/referring-domains/{domain}/` | Referring domains |
| GET | `/integration/ahrefs/organic-keywords/{domain}/` | Organic keywords |
| POST | `/integration/ahrefs/verify-backlinks/` | Bulk verify SAGBacklinks |
| POST | `/integration/ahrefs/snapshot/` | Take domain snapshot |

**Backlink Indexing:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/linker/indexing/submit/` | Submit URLs for indexing |
| POST | `/linker/indexing/bulk-submit/` | Bulk submit all live unindexed |
| GET | `/linker/indexing/requests/` | List requests (filter by site_id) |
| GET | `/linker/indexing/requests/{id}/` | Single request status |
| GET | `/linker/indexing/stats/` | Success rate, pending count |

**Admin Dashboard:**
| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/services/dashboard/` | Revenue summary, client count, MRR |
| GET | `/services/dashboard/overdue/` | Overdue deliverables |
| GET | `/services/dashboard/margin/` | Margin tracking across orders |

### Celery Tasks

| Task | Schedule | Purpose |
|------|----------|---------|
| `onboard_managed_client` | On-demand | Full onboarding flow |
| `process_managed_billing` | Monthly (1st) | Invoice all active subscriptions |
| `reset_monthly_counters` | Monthly (1st) | Reset articles_published counters |
| `check_delivery_status` | Daily | Flag subscriptions behind on deliverables |
| `sync_ahrefs_domain_snapshot` | Weekly | Pull DR/traffic/referring domains per connected site |
| `verify_backlinks_via_ahrefs` | Weekly | Cross-reference SAGBacklinks with Ahrefs data |
| `submit_backlinks_for_indexing` | Daily | Submit live unindexed backlinks |
| `check_indexing_status` | Daily | Check submitted URLs (after 7-day wait) |
| `detect_lost_backlinks_ahrefs` | Weekly | Compare Ahrefs lost links with SAGBacklink records |

### Services

| Service | Purpose |
|---------|---------|
| `ManagedBillingService` | Subscription CRUD, billing, margin calculation |
| `AhrefsService` | API client wrapper, rate limiting, credit tracking |
| `BacklinkIndexingService` | Submit to indexing service, track status, retry logic |

---

## 4. IMPLEMENTATION STEPS

### Build Sequence

**Week 1: Foundation**
1. Create `services` app under `igny8_core/services/`
2. Create `ManagedServiceSubscription` model + migration
3. Create `BacklinkServiceOrder` model + migration
4. Create serializers + viewsets for both
5. Build `ManagedBillingService` — subscription CRUD, billing integration
6. Build onboarding Celery task

**Week 2: Ahrefs + Indexing**
1. Create `AhrefsConnection` + `AhrefsDomainSnapshot` models + migration
2. Build `AhrefsService` — API client with rate limiting and credit tracking
3. Create `BacklinkIndexingRequest` model + migration
4. Build `BacklinkIndexingService` — multi-provider submission
5. Add 5 new fields to `SAGBacklink` model + migration
6. Wire up all Celery tasks

**Week 3: API + Dashboard**
1. Register all API endpoints
2. Build admin dashboard endpoints (revenue, overdue, margin)
3. Build onboarding flow end-to-end
4. Test full managed service lifecycle

---

## 5. ACCEPTANCE CRITERIA

### Managed Services
- [ ] `ManagedServiceSubscription` creates for Lite and Pro tiers
- [ ] Onboarding flow: verify plugin → generate blueprint → configure automation → welcome email
- [ ] Monthly billing generates invoices via existing Stripe/PayPal integration
- [ ] `articles_published` counter tracks against `articles_per_month` target
- [ ] Pause/resume/cancel flows work without data loss
- [ ] Service config JSON stores per-site automation, social, backlink settings

### Backlink Orders
- [ ] `BacklinkServiceOrder` tracks full lifecycle: draft → approved → in_progress → delivered → completed
- [ ] Links tracker: ordered vs delivered vs live vs indexed counts accurate
- [ ] Margin calculated correctly with niche surcharges
- [ ] Orders linkable to SAGCampaign (02E)

### Ahrefs Integration
- [ ] API key stored encrypted, connection test validates key
- [ ] Domain metrics endpoint returns DR, referring domains, traffic, keywords
- [ ] Weekly snapshots auto-populate `AhrefsDomainSnapshot`
- [ ] Backlink verification cross-references SAGBacklink records
- [ ] Lost backlink detection flags dead links
- [ ] Credits consumption tracked

### Backlink Indexing
- [ ] `BacklinkIndexingRequest` tracks full lifecycle: queued → submitted → checking → indexed/failed
- [ ] Submissions go to configured indexing service API
- [ ] 7-day wait before first check, re-submit at 14 days, fail at 28 days
- [ ] Cost tracking per submission
- [ ] `SAGBacklink.is_indexed` updated when confirmed

### Admin Dashboard
- [ ] Revenue summary shows total MRR, client count by tier
- [ ] Overdue endpoint flags behind-schedule content/links
- [ ] Margin tracking shows per-order and aggregate margins

---

## 6. CLAUDE CODE INSTRUCTIONS

### Context Requirements
1. Read 02E (Linker External) — SAGCampaign, SAGBacklink, CampaignKPISnapshot models
2. Read existing billing app models — Plan, Subscription, CreditService
3. Read 03B (WP Plugin Connected) — content delivery flow that managed services triggers
4. Read automation app — AutomationConfig, AutomationRun for pipeline configuration

### Execution Order
```
services app skeleton → models + migrations → ManagedBillingService → AhrefsService →
BacklinkIndexingService → API endpoints → Celery tasks → admin dashboard
```

### Critical Rules
1. **All IDs are integers** — BigAutoField PKs, integer FKs
2. **Model names PLURAL** — Clusters, Keywords, Tasks, etc.
3. **Table prefix** — `igny8_` for all tables
4. **App label** — `services` for new app
5. **Celery app** — `igny8_core` (same as all other tasks)
6. **API pattern** — `/api/v1/services/` for managed service endpoints, `/api/v1/integration/ahrefs/` for Ahrefs, `/api/v1/linker/indexing/` for indexing
7. **AccountBaseModel** for account-scoped models, **SiteSectorBaseModel** for site-scoped
8. **Encrypt API keys** — Ahrefs API key encrypted at rest
9. **Rate limiting** — respect Ahrefs API rate limits, exponential backoff on 429
10. **No blocking** — all external API calls in Celery tasks, never in request/response cycle

### Cross-References

| Doc | Relationship |
|-----|-------------|
| 02E Linker External | SAGCampaign, SAGBacklink models — backlink orders link to these |
| 02C GSC Integration | GSCMetricsCache — monitoring data for Pro tier, indexing status |
| 02D Linker Internal | SAGLink, LinkMap — internal linking health for service delivery |
| 02H Socializer | SocialPost, SocialAccount — social content for Pro tier |
| 02G Rich Schema SERP | SchemaTemplate — retroactive schema enhancement for Pro tier |
| 01A SAG Data Foundation | SAGBlueprint — auto-generated during onboarding |
| 03B WP Plugin Connected | Content delivery to WordPress via sync endpoints |
| 04B Whitelabel Reporting | Reports consume subscription + order data from this doc |
| 04C Pricing Launch | Feature gates control who can purchase managed services |