igny8/v2/V2-Execution-Docs/04A-managed-services.md

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