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