Files

IGNY8 VPS (Salman) 0570052fec 1

2026-03-23 17:20:51 +00:00

40 KiB

Raw Blame History

Phase 4 Build Plan — Business Layer (3 Docs)

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

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

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

Primary Keys

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

Model Names (PLURAL)

Clusters (not Cluster), Keywords (not Keyword), Tasks (not Task)
ContentIdeas (not ContentIdea), Images (not Image), Content (stays singular)

App Structure

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

Verified Codebase Versions

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

Model Inheritance

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

Frontend Stack

TypeScript .tsx files, Zustand state management, Vitest + Playwright testing

Source of Truth

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

DOC STRUCTURE STANDARD

Every doc MUST follow this structure:

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

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

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

Existing Billing Models (billing app)

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

Existing Credit System

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

Current Plans (live)

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

Payment Infrastructure

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

Existing Integration Infrastructure

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

Phase 2 Models Phase 4 Depends On

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

DOC 04A: managed-services.md

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

Source Material:

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

What to Cover:

1. Current State:

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

2. What to Build:

Managed Service Tiers:

Managed Lite ($100/site/month):

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

Managed Pro ($399/site/month):

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

Backlink Service Packages (Managed Mode — Alorig Executes):

By quality level:

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

Monthly retainer packages:

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

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

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

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

Ahrefs API endpoints to integrate:

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

Use cases in IGNY8:

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

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

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

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

Indexing service options (integrate best available):

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

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

Integration flow:

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

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

Client Onboarding Automation:

When ManagedServiceSubscription is created:

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

Monthly delivery workflow (Lite):

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

Monthly delivery workflow (Pro — adds to Lite):

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

3. Data Models & APIs:

New models (in new services app):

ManagedServiceSubscription (extends AccountBaseModel)
- site ForeignKey to Site
- tier CharField (lite/pro)
- status CharField (pending/active/paused/cancelled)
- monthly_price DecimalField(max_digits=8, decimal_places=2)
- articles_per_month IntegerField
- account_manager ForeignKey to User (nullable) — assigned team member
- current_month_articles_published IntegerField (default 0)
- current_month_start DateField (nullable)
- service_config JSONField — per-site settings (automation, social, backlinks, reporting)
- started_at DateTimeField (nullable)
- cancelled_at DateTimeField (nullable)
- next_billing_date DateField (nullable)
- Table: igny8_managed_service_subscriptions
BacklinkServiceOrder (extends AccountBaseModel)
- site ForeignKey to Site
- campaign ForeignKey to SAGCampaign (nullable)
- managed_subscription ForeignKey to ManagedServiceSubscription (nullable)
- order_type CharField (one_time/monthly)
- package CharField (starter/growth/authority/enterprise/custom)
- client_price DecimalField(max_digits=10, decimal_places=2)
- actual_cost DecimalField(max_digits=10, decimal_places=2, default=0)
- margin DecimalField(max_digits=10, decimal_places=2, default=0)
- niche_surcharge FloatField (default 1.0)
- links_ordered IntegerField (default 0)
- links_delivered IntegerField (default 0)
- links_live IntegerField (default 0)
- links_indexed IntegerField (default 0)
- status CharField (draft/approved/in_progress/delivered/completed)
- ordered_at DateTimeField (nullable)
- delivered_at DateTimeField (nullable)
- notes TextField (blank)
- Table: igny8_backlink_service_orders
AhrefsConnection (extends AccountBaseModel)
- api_key TextField (encrypted)
- plan_type CharField (nullable) — lite/standard/advanced/enterprise
- credits_remaining IntegerField (nullable)
- last_synced DateTimeField (nullable)
- status CharField (active/expired/error)
- Table: igny8_ahrefs_connections
AhrefsDomainSnapshot (extends SiteSectorBaseModel)
- domain CharField
- domain_rating FloatField
- referring_domains IntegerField
- organic_keywords IntegerField
- organic_traffic IntegerField
- backlinks_total IntegerField
- snapshot_date DateField
- raw_data JSONField — full API response
- Table: igny8_ahrefs_domain_snapshots
BacklinkIndexingRequest (extends SiteSectorBaseModel)
- backlink ForeignKey to SAGBacklink
- url URLField — the backlink source URL to be indexed
- indexing_service CharField (speedyindex/omega/colossus/indexnow/manual)
- service_request_id CharField (nullable) — external service reference
- submitted_at DateTimeField (nullable)
- first_check_at DateTimeField (nullable)
- last_check_at DateTimeField (nullable)
- check_count IntegerField (default 0)
- is_indexed BooleanField (default False)
- indexed_at DateTimeField (nullable)
- status CharField (queued/submitted/checking/indexed/failed/resubmitted)
- cost DecimalField(max_digits=6, decimal_places=4, default=0)
- Table: igny8_backlink_indexing_requests

Modified models:

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

New endpoints:

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

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

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

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

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

Celery tasks:

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

Services:

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

Margin Analysis:

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

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

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

DOC 04B: whitelabel-reporting.md

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

Source Material:

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

What to Cover:

1. Current State:

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

2. What to Build:

Report Generation Engine:

9 configurable report sections (each can be included/excluded per client):

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

Data sources per section:

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

PDF Report Generation:

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

White-Label Branding (Agency Play):

For agencies reselling IGNY8 services to their clients:

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

Admin Services Dashboard (Alorig team only):

Frontend pages (TypeScript .tsx):

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

Sidebar addition (admin-only, behind managed_services_enabled feature flag):

ADMIN
  ├── Sector Templates
  └── Managed Services (NEW)

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

Frontend pages:

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

Sidebar addition (only shows if ManagedServiceSubscription exists for account):

ACCOUNT
  ├── Account Settings
  ├── Plans & Billing
  ├── Managed Service (NEW — conditional)
  ├── Usage
  └── AI Models

3. Data Models & APIs:

New models (in services app):

ServiceReport (extends AccountBaseModel)
- site ForeignKey to Site
- managed_subscription ForeignKey to ManagedServiceSubscription (nullable)
- report_type CharField (weekly/monthly/quarterly)
- period_start DateField
- period_end DateField
- report_data JSONField — all metrics for period (structured by section)
- report_pdf_url URLField (blank) — generated PDF in S3
- is_white_label BooleanField (default False)
- branding ForeignKey to AgencyBranding (nullable)
- sections_included JSONField — list of included section keys
- generated_at DateTimeField (auto_now_add)
- sent_at DateTimeField (nullable)
- sent_to JSONField — list of email addresses sent to
- Table: igny8_service_reports
AgencyBranding (extends AccountBaseModel)
- brand_name CharField(max_length=200)
- brand_logo_url URLField (blank)
- primary_color CharField(max_length=7) — hex color
- secondary_color CharField(max_length=7) — hex color
- contact_email EmailField (blank)
- contact_phone CharField (blank)
- website_url URLField (blank)
- footer_text TextField (blank)
- is_active BooleanField (default True)
- Table: igny8_agency_branding
ReportTemplate (extends AccountBaseModel)
- name CharField
- template_html TextField — base HTML template
- template_css TextField — custom CSS
- is_default BooleanField
- branding ForeignKey to AgencyBranding (nullable) — agency-specific template
- Table: igny8_report_templates

New endpoints:

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

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

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

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

Celery tasks:

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

Services:

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

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

DOC 04C: pricing-launch.md

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

Source Material:

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

What to Cover:

1. Current State:

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

2. What to Build:

Updated Plan Feature Matrix:

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

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

Feature Flag System:

Extend existing Plan model with feature capabilities:

New model: PlanFeature (or JSON field on Plan):

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

Feature gate checking pattern:

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

Middleware/decorator:

@require_feature('linker_level', 'auto')
def auto_insert_links(self, request):
    ...

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

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

WordPress.org Plugin Submission:

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

Submission checklist:

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

Review timeline: typically 1-4 weeks for initial review

Post-approval:

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

Go-to-Market Strategy:

Target audiences:

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

Funnel:

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

Launch Sequence:

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

Launch steps:

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

Existing User Migration:

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

3. Data Models & APIs:

Modified models:

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

New model:

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

New endpoints:

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

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

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

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

Celery tasks:

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

Services:

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

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

BUILD SEQUENCE

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

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

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

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

For each doc:

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

SOURCE FILES TO READ

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

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

40 KiB Raw Blame History Unescape Escape

Phase 4 Build Plan — Business Layer (3 Docs)

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

Primary Keys

Model Names (PLURAL)

App Structure

Verified Codebase Versions

Model Inheritance

Frontend Stack

Source of Truth

DOC STRUCTURE STANDARD

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

Existing Billing Models (billing app)

Existing Credit System

Current Plans (live)

Payment Infrastructure

Existing Integration Infrastructure

Phase 2 Models Phase 4 Depends On

DOC 04A: managed-services.md

Source Material:

What to Cover:

DOC 04B: whitelabel-reporting.md

Source Material:

What to Cover:

DOC 04C: pricing-launch.md

Source Material:

What to Cover:

BUILD SEQUENCE

SOURCE FILES TO READ

40 KiB

Raw Blame History