igny8/docs/10-BACKEND/MODELS.md

Domain Models

Purpose

Describe the key backend models, their responsibilities, constraints, and tenancy rules, grounded in current implementations.

Code Locations (exact paths)

• Tenancy bases and identity: backend/igny8_core/auth/models.py
• Planner models: backend/igny8_core/business/planning/models.py
• Writer/content models: backend/igny8_core/business/content/models.py
• Automation models: backend/igny8_core/business/automation/models.py
• Billing models: backend/igny8_core/business/billing/models.py
• Integration models: backend/igny8_core/business/integration/models.py
• Publishing models: backend/igny8_core/business/publishing/models.py
• Optimization models: backend/igny8_core/business/optimization/models.py

High-Level Responsibilities

• Provide tenant-scoped storage for planner (keywords/clusters/ideas), writer (tasks/content/taxonomies/images/attributes), automation runs/config, billing (credits, invoices, payments), integration metadata, publishing records, and optimization tasks.
• Enforce account/site/sector alignment via base classes and save-time validation.
• Track external platform links (WordPress/Shopify/custom), credit usage, and publishing/optimization state.

Detailed Behavior

Tenancy Bases (auth/models.py)

• AccountBaseModel: adds account, timestamps, and indexes; all tenant models inherit.
• SiteSectorBaseModel: extends with site and sector; save enforces site → account alignment and sector belonging to the same site; raises validation errors if mismatched.

Planner (business/planning/models.py)

• Clusters: tenant/site/sector-scoped keyword group; tracks counts, volume, mapped pages, status (new/mapped), disable flag; unique per site/sector by name; soft-deletable.
• Keywords: tenant/site/sector-scoped keyword tied to a global SeedKeyword; optional overrides for volume/difficulty/attributes; optional cluster link (same sector enforced); validation ensures seed keyword industry/sector matches site/sector; status (new/mapped), disable flag; soft-deletable.
• ContentIdeas: ideas tied to clusters and optional keywords; tracks status (new/queued/completed), content type/structure, estimated word count; soft-deletable.

Writer / Content (business/content/models.py)

• Tasks: queue items for content generation; tied to cluster (required) and optional idea/taxonomy; content type/structure, keywords text, target word count, status (queued/completed); soft-deletable.
• Content: generated or imported content; stores HTML, word count, SEO fields, cluster link, content type/structure, taxonomy M2M, external IDs/URLs/metadata, sync status, source (igny8/wordpress), and status (draft/review/published); soft-deletable.
• ContentTaxonomy: simplified taxonomy (category/tag) with external taxonomy/ID, sync status, description, count, metadata; unique per site by slug/type and by external ID/taxonomy.
• Images: images linked to content or task; auto-populates account/site/sector from the linked object; tracks type, URL/path, prompt, status, position; soft-deletable.
• ContentClusterMap: maps content/tasks to clusters with role (hub/supporting/attribute) and source (blueprint/manual/import); auto-populates tenant context from linked content/task; unique per content+cluster+role.
• ContentAttribute (alias ContentAttributeMap): tenant/site/sector-scoped attributes for content/task/cluster; typed (product_spec/service_modifier/semantic_facet), with optional external IDs, sources, and metadata; auto-populates tenant context from linked content/task.

Automation (business/automation/models.py)

• AutomationConfig: per-site config with enable flag, frequency (daily/weekly/monthly), scheduled time, batch sizes per stage, within/between-stage delays, and next/last run timestamps.
• AutomationRun: tracks each run with trigger (manual/scheduled), status (running/paused/cancelled/completed/failed), current stage, pause/cancel timestamps, start/end, total credits used, per-stage JSON results, and optional error message.

Billing (business/billing/models.py)

• CreditTransaction: ledger of credit changes (purchase/subscription/refund/deduction/adjustment) with balance-after and metadata.
• CreditUsageLog: detailed AI usage log with operation type (clustering/idea/content/image/reparse/legacy names), credits used, optional cost/model/tokens, related object references, and metadata.
• CreditCostConfig: admin-configurable credit costs per operation with unit (per request/words/items/images), display metadata, active flag, audit fields, and previous cost tracking.
• Invoice: tenant invoice with amounts, status (draft/pending/paid/void/uncollectible), dates, subscription link, line items JSON, payment metadata, Stripe IDs, notes; helper properties mirror legacy fields.
• Payment: payment records per invoice with status lifecycle (pending/processing/succeeded/completed/failed/refunded/cancelled), method (Stripe/PayPal/bank/local wallet/manual), provider references, manual notes/approval fields, failure reason, timestamps, metadata.
• CreditPackage: one-time credit bundles with price, discount, Stripe/PayPal IDs, active/featured flags, description/features, sort order.
• PaymentMethodConfig: per-country payment-method availability and display/instruction fields; includes bank/local wallet metadata; unique per country+method.
• AccountPaymentMethod: account-level payment metadata (non-sensitive) with type, display name, default/enabled/verified flags, country code, instructions, metadata; unique per account+display name.

Integration (business/integration/models.py)

• SiteIntegration: tenant/site-specific integration config with platform (wordpress/shopify/custom), platform type (cms/ecommerce/custom_api), config JSON, credentials JSON, active/sync flags, sync status, last sync/error, timestamps; unique per site+platform.
• SyncEvent: event log per integration/site with event/action types, success flag, optional content/external IDs, details JSON, error, duration, and timestamps; indexed for debugging feeds.

Publishing (business/publishing/models.py)

• PublishingRecord: tracks content publishing to destinations (wordpress/sites/shopify) with destination IDs/URLs, status (pending/publishing/published/failed), timestamps, errors, metadata; site/sector scoped via base.
• DeploymentRecord: tracks site deployments (sites renderer) with version/deployed_version, status (pending/deploying/deployed/failed/rolled_back), deployment URL, error, metadata, timestamps; site/sector scoped.

Optimization (business/optimization/models.py)

• OptimizationTask: content optimization runs with before/after scores and HTML, status (pending/running/completed/failed), credits used, metadata; auto-sets account from content; tenant scoped.

Execution Flow

• Tenant context is inherited from base models; many save methods propagate account/site/sector from related entities (e.g., Images, ContentClusterMap, ContentAttribute).
• Planner → Writer linkage: Keywords and Clusters feed ContentIdeas; Tasks reference clusters/ideas; Content references clusters and taxonomies; Images/Attributes link to Tasks/Content.
• Automation runs reference planner/writer models and record per-stage outputs; configs control batching/delays.
• Billing logs and cost configs govern credit debits triggered by services (see services doc).
• Integration/publishing models bind site integrations and publishing deployments to site-scoped content.
• Optimization tasks attach to content and capture before/after artifacts.

Cross-Module Interactions

• Planner and writer share clusters/ideas/tasks/content relationships.
• Billing models are invoked by services during AI/automation/image/content operations.
• Integration events reference content IDs and external IDs for sync traces.
• Publishing records reference writer content; deployment records reference sites.
• Optimization tasks reference writer content and can influence publishing readiness downstream.

State Transitions (if applicable)

• Soft-delete is available on planner keywords/clusters/ideas and writer tasks/content/images via SoftDeletableModel.
• Status fields track lifecycle: planner (new/mapped/queued/completed), writer tasks (queued/completed), content (draft/review/published), automation (running/paused/cancelled/completed/failed), publishing/deployment statuses, payment/invoice statuses, optimization statuses.

Error Handling

• Save-time validation in SiteSectorBaseModel and Keywords ensures tenant/site/sector alignment and industry/sector matching.
• Unique constraints prevent duplicate clusters/keywords per site/sector and overlapping taxonomies/external IDs.
• Automation runs store error messages and partial stage results; publishing/deployment records store error text.

Tenancy Rules

• All models shown are tenant scoped via AccountBaseModel or SiteSectorBaseModel; save hooks propagate context from related objects where needed.
• Privileged roles can bypass filtering at the viewset layer, but persisted records retain account/site/sector ownership.

Billing Rules (if applicable)

• Credits reside on Account; transactions/usage logs record debits/credits; cost configs define per-operation pricing.
• Invoices/payments/credit packages configure monetary flows; payment methods can be toggled per country or per account.

Background Tasks / Schedulers (if applicable)

• Automation configs drive scheduled runs; automation runs record stage outputs and timing.
• Publishing/optimization tasks may be executed async via services/Celery (see services doc).

Key Design Considerations

• Tenant isolation is encoded at the model layer via base classes and validation, ensuring downstream services inherit scoping.
• Cross-module links (clusters ↔ tasks ↔ content ↔ publishing/optimization) keep content lifecycle traceable.
• Billing and integration models include metadata fields to avoid schema churn while capturing provider-specific details.

How Developers Should Work With This Module

• Inherit new tenant models from AccountBaseModel or SiteSectorBaseModel to enforce scoping automatically.
• Validate cross-entity alignment (site/sector/industry) when relating planner and writer records.
• Use existing status fields/choices when extending lifecycles; preserve unique constraints when adding fields.
• When integrating new providers, extend or add models parallel to SiteIntegration/SyncEvent and keep platform-specific data in JSON fields.