487 lines
22 KiB
Markdown
487 lines
22 KiB
Markdown
# 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 |
|