docs re-org

docs/.structure-plan.txt

@@ -0,0 +1,119 @@
+FINAL DOCUMENTATION STRUCTURE
+==============================
+
+docs/
+├── README.md (Master navigation - find anything in 1 step)
+├── CHANGELOG.md (All changes across system)
+│
+├── 00-SYSTEM/
+│   ├── ARCHITECTURE-OVERVIEW.md (High-level system design)
+│   ├── TECH-STACK.md (All technologies used)
+│   ├── MULTITENANCY.md (Account isolation, tenant context)
+│   ├── AUTHENTICATION.md (JWT, sessions, permissions)
+│   └── DATA-FLOWS.md (Visual workflows across system)
+│
+├── 10-BACKEND/
+│   ├── OVERVIEW.md (Backend architecture)
+│   ├── MODELS.md (All database models with fields)
+│   ├── SERVICES.md (Business logic services)
+│   │
+│   ├── accounts/
+│   │   └── ACCOUNTS-REFERENCE.md (User, Account, Role models + endpoints)
+│   │
+│   ├── billing/
+│   │   ├── BILLING-REFERENCE.md (Plans, Subscriptions, Invoices)
+│   │   ├── CREDITS-SYSTEM.md (Credit allocation/deduction)
+│   │   └── PAYMENT-METHODS.md (Payment processing)
+│   │
+│   ├── planner/
+│   │   ├── PLANNER-REFERENCE.md (Keywords → Clusters → Ideas)
+│   │   ├── KEYWORD-CLUSTERING.md (Clustering algorithm)
+│   │   └── IDEA-GENERATION.md (AI-powered idea generation)
+│   │
+│   ├── writer/
+│   │   ├── WRITER-REFERENCE.md (Content generation)
+│   │   ├── CONTENT-GENERATION.md (AI content creation flow)
+│   │   ├── IMAGES-SYSTEM.md (Image generation & management)
+│   │   └── PUBLISHING.md (Review & publish workflow)
+│   │
+│   ├── automation/
+│   │   ├── AUTOMATION-REFERENCE.md (Full automation pipeline)
+│   │   ├── PIPELINE-STAGES.md (Stage-by-stage breakdown)
+│   │   └── SCHEDULER.md (Celery tasks & scheduling)
+│   │
+│   ├── integrations/
+│   │   ├── WORDPRESS-INTEGRATION.md (WP sync & publishing)
+│   │   ├── AI-SERVICES.md (OpenAI, Anthropic integration)
+│   │   └── IMAGE-GENERATION.md (DALL-E, Stability AI)
+│   │
+│   └── sites/
+│       └── SITES-REFERENCE.md (Site & Sector management)
+│
+├── 20-API/
+│   ├── API-REFERENCE.md (All REST endpoints)
+│   ├── AUTHENTICATION-ENDPOINTS.md (Login, register, tokens)
+│   ├── PLANNER-ENDPOINTS.md (Keywords, clusters, ideas)
+│   ├── WRITER-ENDPOINTS.md (Content, tasks, images)
+│   ├── AUTOMATION-ENDPOINTS.md (Automation runs)
+│   ├── BILLING-ENDPOINTS.md (Invoices, payments, credits)
+│   └── INTEGRATION-ENDPOINTS.md (WordPress, external services)
+│
+├── 30-FRONTEND/
+│   ├── FRONTEND-ARCHITECTURE.md (React structure, routing)
+│   ├── STATE-MANAGEMENT.md (Zustand stores)
+│   ├── COMPONENTS.md (Reusable UI components)
+│   │
+│   ├── planner/
+│   │   └── PLANNER-UI.md (Keywords, clusters, ideas pages)
+│   │
+│   ├── writer/
+│   │   └── WRITER-UI.md (Content, tasks, publishing pages)
+│   │
+│   ├── automation/
+│   │   └── AUTOMATION-UI.md (Automation dashboard)
+│   │
+│   └── billing/
+│       └── BILLING-UI.md (Plans, payments, invoices)
+│
+├── 40-WORKFLOWS/
+│   ├── SIGNUP-TO-ACTIVE.md (User journey from signup to active)
+│   ├── CONTENT-LIFECYCLE.md (Keyword → Idea → Task → Content → Published)
+│   ├── PAYMENT-WORKFLOW.md (Manual payment approval flow)
+│   ├── AUTOMATION-WORKFLOW.md (Full automation run lifecycle)
+│   └── WORDPRESS-SYNC.md (Bidirectional sync workflow)
+│
+├── 50-DEPLOYMENT/
+│   ├── ENVIRONMENT-SETUP.md (Local, staging, production)
+│   ├── DOCKER-DEPLOYMENT.md (Container setup)
+│   └── DATABASE-MIGRATIONS.md (Migration strategy)
+│
+└── 90-ARCHIVED/
+    └── (Old deprecated docs for reference)
+
+NAVIGATION RULES
+================
+
+1. Master README.md has "Quick Find" table:
+   - Want to add feature? → Find module → Find file
+   - Want to troubleshoot? → Find workflow → Find exact function
+   - Want API details? → Find endpoint → See request/response/location
+
+2. Every doc file has:
+   - Purpose statement
+   - File locations (exact paths)
+   - Function/Class names (no code)
+   - Related files (cross-references)
+   - Data flow (if applicable)
+
+3. No code snippets, only:
+   - File paths: backend/igny8_core/business/billing/services/credit_service.py
+   - Function names: CreditService.add_credits()
+   - Model fields: account.credits, invoice.total
+   - Endpoints: POST /v1/billing/admin/payments/confirm/
+
+4. Visual elements allowed:
+   - ASCII flow diagrams
+   - State transition tables
+   - Field mapping tables
+   - Workflow sequences
+

docs/00-SYSTEM/ARCHITECTURE-OVERVIEW.md

@@ -0,0 +1,79 @@
+# System Architecture Overview
+
+## Purpose
+Describe how IGNY8 is structured across backend, frontend, and integrations, grounded in the current codebase. Covers core services, middleware, and platform composition.
+
+## Code Locations (exact paths)
+- Backend project root: `backend/igny8_core/`
+- Settings and service wiring: `backend/igny8_core/settings.py`
+- URL routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/middleware/resource_tracker.py`, `backend/igny8_core/auth/middleware.py`
+- Auth models and tenancy bases: `backend/igny8_core/auth/models.py`
+- DRF base behaviors: `backend/igny8_core/api/base.py`
+- Custom auth classes: `backend/igny8_core/api/authentication.py`
+- Frontend SPA: `frontend/` (Vite + React; dependencies in `frontend/package.json`)
+
+## High-Level Responsibilities
+- Django/DRF backend providing multi-tenant APIs for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
+- Middleware adds per-request IDs, tenant context, and optional resource tracking for admin diagnostics.
+- REST API routing under `/api/v1/*` with unified response/error handling and scoped throttling.
+- Celery-backed async work (configured in settings) for AI, automation, and publishing.
+- React/Vite frontend consuming the API; authentication via JWT or session; API key support for WordPress bridge.
+
+## Detailed Behavior
+- Backend apps registered in `INSTALLED_APPS` include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, and publisher modules; these are loaded via Django app configs in `settings.py`.
+- Middleware order enforces security, CORS, session, CSRF, Django auth, then custom layers: request ID, account context, resource tracking, messages, and clickjacking protection.
+- URL map (`urls.py`) exposes admin, CSV admin utilities for industries/seed keywords, and module routers for auth, account, planner, writer, system, billing (user + admin), automation, linker, optimizer, publisher, and integration. OpenAPI docs available at `/api/docs` and `/api/redoc`.
+- REST framework defaults use custom pagination, filtering, search, ordering, and a custom exception handler (enabled unless `IGNY8_USE_UNIFIED_EXCEPTION_HANDLER` is false). Authentication stack orders API key, JWT, CSRF-exempt session, then basic auth. Throttle scopes are predefined per domain (AI, content, auth, planner, writer, system, billing, linker, optimizer, integration).
+- CORS allows the IGNY8 domains plus local development hosts; credentials and specific debug headers are permitted, and request/resource tracking IDs are exposed in response headers.
+- Celery is configured to use Redis by default for broker and result backend, with JSON serialization, task time limits, and single-prefetch workers.
+- Logging writes to console and rotating files for publish/sync, WordPress API calls, and webhooks, with request IDs available via middleware.
+
+## Data Structures / Models Involved (no code, just explanation)
+- Multi-tenancy base classes (`AccountBaseModel`, `SiteSectorBaseModel`) add `account`, `site`, and `sector` scoping plus validation; defined in `auth/models.py`.
+- Core tenancy entities: `Account`, `Plan`, `Subscription`, `Site`, `Sector`, `Industry`, `IndustrySector`, `SeedKeyword`, `SiteUserAccess`, `User`, and `PasswordResetToken` in `auth/models.py`.
+- These bases are consumed by downstream modules (planner, writer, billing, automation, etc.) to enforce tenant, site, and sector ownership.
+
+## Execution Flow
+- Incoming HTTP requests enter Django middleware: security → WhiteNoise → CORS → session → common/CSRF → Django auth → `RequestIDMiddleware` (assigns `X-Request-ID`) → `AccountContextMiddleware` (sets `request.account` via session or JWT) → `ResourceTrackingMiddleware` (when enabled for admins) → messages → clickjacking.
+- DRF viewsets inherit from base classes in `api/base.py` to auto-filter querysets by account (and site/sector where applicable) and emit unified responses.
+- URL dispatch routes to module-specific routers under `/api/v1/*`. CSV admin helpers are mounted before admin to avoid routing conflicts.
+- Background tasks are dispatched via Celery using Redis endpoints from `settings.py`.
+
+## Cross-Module Interactions
+- Auth middleware sets `request.account` consumed by `AccountModelViewSet` and `SiteSectorModelViewSet` to filter data.
+- API key auth (WordPress bridge) sets both `request.account` and `request.site` for integration endpoints.
+- Resource tracking middleware exposes metrics via cache keyed by the request-specific tracking ID added to responses.
+- OpenAPI generation (drf-spectacular) documents all modules and respects unified response schemas.
+
+## State Transitions (if applicable)
+- Request lifecycle: ID assignment → tenant resolution → optional resource profiling → viewset execution → unified response with optional pagination and request/resource IDs in headers.
+- Tenancy lifecycle: Account/Plan/Subscription fields in models track status and retention; soft delete support on models that implement it.
+
+## Error Handling
+- Global DRF exception handler (custom when enabled) wraps errors into unified JSON with `success=false`.
+- Account middleware denies access when account or plan is missing/inactive, returning structured JSON and logging out session users.
+- Viewset overrides in `api/base.py` return unified error payloads for validation and 404/500 cases.
+
+## Tenancy Rules
+- Account is injected via middleware (session or JWT). Base viewsets filter querysets by `account`, unless the user is admin/developer/system account (override path).
+- `SiteSectorModelViewSet` adds site/sector filtering when models carry those fields; validation ensures site/sector belong to the same account.
+- Role helpers (`User.is_admin_or_developer`, `User.is_system_account_user`) allow bypass for privileged users; otherwise, data is restricted to the resolved account (and site/sector for derived models).
+
+## Billing Rules (if applicable)
+- Plan and account billing fields live in `auth/models.py` (`Plan.included_credits`, `Account.credits`, Stripe IDs). Status enforcement occurs in `AccountContextMiddleware` by requiring an active plan; billing modules implement credit logic (covered in backend/billing docs).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery configuration in `settings.py` sets Redis broker/backend, JSON serialization, time limits, and worker tuning. Task modules (AI, automation, publishing) use this setup; scheduling uses Celery Beat state.
+
+## Key Design Considerations
+- Middleware-first tenant resolution ensures consistent scoping before view logic.
+- Admin/developer/system-account overrides allow cross-tenant operations for ops while protecting system accounts from deletion.
+- Unified API responses and throttling scopes enforce consistent client behavior and rate safety.
+- Redis-backed Celery keeps async workloads out of request path with strict time limits.
+
+## How Developers Should Work With This Module
+- Add new apps to `INSTALLED_APPS` and mount URLs under `/api/v1/*` in `urls.py`.
+- Inherit from `AccountModelViewSet` or `SiteSectorModelViewSet` to automatically enforce tenant/site/sector scoping and unified responses.
+- Use existing middleware; do not reorder request ID or account context layers, as downstream views rely on them.
+- Configure environment via `settings.py` variables (DB, JWT, Celery, CORS, Stripe/PayPal) rather than hardcoding values.

docs/00-SYSTEM/AUTHENTICATION.md

@@ -0,0 +1,73 @@
+# Identity and Authentication
+
+## Purpose
+Document how user identity, JWT handling, API keys, and session flows work, including middleware and validation rules.
+
+## Code Locations (exact paths)
+- JWT utilities: `backend/igny8_core/auth/utils.py`
+- Account context middleware: `backend/igny8_core/auth/middleware.py`
+- DRF authentication classes: `backend/igny8_core/api/authentication.py`
+- DRF settings for auth/throttle: `backend/igny8_core/settings.py`
+- User model and roles: `backend/igny8_core/auth/models.py`
+- Auth URLs and views: `backend/igny8_core/auth/urls.py`, `backend/igny8_core/auth/views.py`
+
+## High-Level Responsibilities
+- Support multiple auth mechanisms: API key (WordPress bridge), JWT bearer tokens, session auth without CSRF for APIs, and basic auth fallback.
+- Populate tenant/site context alongside user identity so downstream viewsets enforce isolation.
+- Enforce active account/plan presence before serving protected endpoints (except admin/auth routes).
+
+## Detailed Behavior
+- Authentication order (DRF `DEFAULT_AUTHENTICATION_CLASSES` in `settings.py`): API key → JWT → CSRF-exempt session → basic auth. The first class that authenticates sets `request.user`; `request.account` may also be set by API key or JWT.
+- API Key flow (`APIKeyAuthentication`): expects `Authorization: Bearer <api_key>` that is not JWT-like; finds an active `Site` with `wp_api_key`, loads its `account`, and selects an active user (owner preferred, else any active developer/owner/admin). Sets `request.account` and `request.site`. Rejects short/invalid keys; returns an auth failure if no active user exists.
+- JWT flow (`JWTAuthentication`): expects `Authorization: Bearer <jwt>`; decodes via `auth.utils.decode_token`; only accepts tokens with `type == access`. Retrieves `User` by `user_id`; optional `account_id` is resolved to `Account` and set on `request.account`. Invalid/expired tokens fall through to other auth classes.
+- Session flow (`CSRFExemptSessionAuthentication`): uses Django session cookies without CSRF enforcement for API calls.
+- Basic auth: last resort; does not set tenant context.
+- Token utilities (`auth/utils.py`) generate and decode access/refresh tokens using expiries from settings (`JWT_ACCESS_TOKEN_EXPIRY`, `JWT_REFRESH_TOKEN_EXPIRY`), embedding `user_id`, `account_id`, `email`, issued/expiry timestamps, and token `type`.
+- Middleware (`AccountContextMiddleware`) runs on every request except admin/auth paths: refreshes session users from DB to pick up current account/plan, validates presence of an active plan, sets `request.account`, and logs out session users when invalid. For JWT-bearing requests it decodes the token directly and sets `request.account`. If account/plan is missing or inactive, it returns JSON with `success=false` and appropriate HTTP status.
+
+## Data Structures / Models Involved (no code)
+- `User` with `role` and `account` FKs in `auth/models.py`.
+- `Account` with plan and billing fields; plan status is used for access gating.
+- `Site` with `wp_api_key` for API key auth; `SiteUserAccess` for per-site grants.
+- `PasswordResetToken` model for password reset flows.
+- JWT payload fields: `user_id`, `account_id`, `email`, `exp`, `iat`, `type`.
+
+## Execution Flow
+- Middleware step: `AccountContextMiddleware` determines `request.account` (session or JWT) and validates plan status; skips admin/auth routes.
+- DRF auth step: API key/JWT/session/basic authenticators run in order, potentially setting `request.account` (API key/JWT) and `request.site` (API key).
+- Viewsets then apply role/permission checks and tenant/site/sector filtering via base classes in `api/base.py`.
+
+## Cross-Module Interactions
+- All module viewsets rely on `request.user` and `request.account` set by the auth stack. Site-aware modules can read `request.site` when API key auth is used.
+- Role helpers (`is_admin_or_developer`, `is_system_account_user`) influence filtering bypass in base viewsets.
+
+## State Transitions (if applicable)
+- JWT lifetimes: access tokens default to 15 minutes; refresh tokens to 30 days (configurable in settings).
+- Session users are refreshed on each request to pick up plan/account changes.
+- Password reset tokens track expiry and usage via `expires_at` and `used` flags.
+
+## Error Handling
+- Middleware returns JSON errors for missing account or inactive plan and logs out session users in those cases.
+- Invalid/expired JWTs cause the JWT authenticator to return `None`, allowing other auth methods; decoding errors raise `InvalidTokenError` in utilities.
+- API key auth raises an auth failure when no active user is available for the resolved account.
+
+## Tenancy Rules
+- `request.account` is set early; base viewsets enforce account filtering unless user has admin/developer/system-account privileges.
+- API key auth also sets `request.site` for integration contexts; site/sector filtering occurs in `SiteSectorModelViewSet`.
+
+## Billing Rules (if applicable)
+- Active plan is required for access (middleware enforces). Credit debits/charges are handled in billing modules, not in the auth layer.
+
+## Background Tasks / Schedulers (if applicable)
+- Token generation/validation is synchronous. Background tasks should receive explicit user/account identifiers in their payloads when invoked.
+
+## Key Design Considerations
+- Authentication stack is ordered to give integration API keys precedence, then JWT for app clients, then session for browser-based flows.
+- Tenant context must be established before view logic; do not move or remove `AccountContextMiddleware`.
+- Expiry durations and JWT secrets are centrally configured in `settings.py`.
+
+## How Developers Should Work With This Module
+- Use token helpers from `auth/utils.py` when issuing tokens; do not handcraft JWTs.
+- Mount new auth-sensitive endpoints under existing routers and rely on DRF auth classes instead of custom header parsing.
+- Ensure new features that require site context can work with API key auth by checking `request.site`.
+- Keep plan enforcement in place; bypass only for admin/system routes when justified.

docs/00-SYSTEM/DATA-FLOWS.md

@@ -0,0 +1,85 @@
+# Data Flow Diagrams (Narrative)
+
+## Purpose
+Describe end-to-end data movement through the system based on current routing, middleware, and model conventions. No diagrams are embedded; flows are explained textually.
+
+## Code Locations (exact paths)
+- Request routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/middleware/resource_tracker.py`
+- DRF base viewsets: `backend/igny8_core/api/base.py`
+- Authentication classes: `backend/igny8_core/api/authentication.py`
+- Tenancy models: `backend/igny8_core/auth/models.py`
+- Celery configuration: `backend/igny8_core/settings.py`
+
+## High-Level Responsibilities
+- Trace how HTTP requests are processed, tenant-scoped, authorized, and persisted.
+- Show where async processing departs to Celery and where responses are shaped.
+
+## Detailed Behavior
+- Incoming request → Django middleware stack:
+  - Security/WhiteNoise/CORS/session/common/CSRF/Django auth.
+  - `RequestIDMiddleware` assigns `request.request_id` and returns it in `X-Request-ID`.
+  - `AccountContextMiddleware` resolves user/account (session or JWT) and enforces active plan; sets `request.account`.
+  - `ResourceTrackingMiddleware` optionally tracks resource usage for admin/developer users when the `X-Debug-Resource-Tracking` header is true; adds `X-Resource-Tracking-ID`.
+- URL dispatch via `urls.py` routes to module routers (auth, account, planner, writer, system, billing, automation, linker, optimizer, publisher, integration) under `/api/v1/*`.
+- DRF viewset pipeline:
+  - Authentication classes (API key → JWT → session → basic) establish `request.user` (and optionally `request.account`/`request.site`).
+  - Base viewsets (`AccountModelViewSet`, `SiteSectorModelViewSet`) filter querysets by `account`/`site`/`sector` and attach `account` on create.
+  - Serializers handle validation; responses are wrapped by unified helpers to standardize success/error payloads and pagination.
+- Persistence:
+  - Tenant-scoped models inherit `AccountBaseModel` or `SiteSectorBaseModel`; save hooks enforce account/site/sector alignment.
+  - Soft deletion is used where models implement `soft_delete`, respecting retention windows from account settings.
+- Async/Background:
+  - Celery uses Redis broker/backend; tasks inherit JSON payloads and time limits from `settings.py`.
+  - Automation, AI, publishing, and billing tasks enqueue via Celery; results return through database/state updates, not synchronous responses.
+- Response:
+  - Unified response wrappers ensure `success`, `data`/`error`, and request ID are present; paginated responses include `count/next/previous/results`.
+  - Throttling headers apply per-scope (as configured in `REST_FRAMEWORK` throttles).
+
+## Data Structures / Models Involved (no code)
+- Tenancy bases: `AccountBaseModel`, `SiteSectorBaseModel`.
+- Core entities: `Account`, `Plan`, `Site`, `Sector`, `User`, `SiteUserAccess`.
+- Module-specific models follow the same tenancy bases (documented in module-specific files).
+
+## Execution Flow
+1) HTTP request hits middleware; IDs and tenant context are set.  
+2) DRF authentication authenticates and sets user/account/site.  
+3) Viewset filters data by tenant/site/sector and runs serializer validation.  
+4) DB operations persist data with enforced tenant alignment.  
+5) Optional Celery tasks are queued for long-running work.  
+6) Response returns unified JSON with request IDs and optional throttling/pagination headers.
+
+## Cross-Module Interactions
+- Auth context set in middleware is consumed by all module viewsets for scoping.
+- API key auth provides site context for integration/publisher flows.
+- Celery configuration is shared by automation/AI/publishing/billing task modules.
+
+## State Transitions (if applicable)
+- Entity lifecycle changes (create/update/delete/soft-delete) flow through base viewsets and tenancy bases, ensuring account/site/sector consistency.
+- Request lifecycle includes request ID creation, optional resource tracking, and unified response wrapping.
+
+## Error Handling
+- Middleware can short-circuit with JSON errors for missing account/plan.
+- Viewset overrides wrap validation and server errors into unified responses; missing objects return 404 payloads.
+- Throttling (scope-based) returns standard DRF throttle responses with headers.
+
+## Tenancy Rules
+- All tenant-bound data flows require `request.account`; filtering and save hooks prevent cross-tenant access.
+- Admin/developer/system-account users may bypass tenant filtering; system accounts are guarded against deletion.
+- Site/sector alignment is validated on save for models inheriting `SiteSectorBaseModel`.
+
+## Billing Rules (if applicable)
+- Plan activation is validated in middleware. Credit debits and billing workflows occur in billing modules (covered elsewhere) after tenant resolution.
+
+## Background Tasks / Schedulers (if applicable)
+- Celery broker/backend configuration in `settings.py` governs async flow; tasks should include account/site identifiers to maintain scoping.
+
+## Key Design Considerations
+- Request ID and resource tracking enable traceability and performance debugging.
+- Middleware ordering ensures tenant context precedes view logic.
+- Unified response format keeps clients consistent across modules.
+
+## How Developers Should Work With This Module
+- Preserve middleware order; new middleware must not break request ID or tenant context.
+- Ensure new viewsets inherit the base classes to pick up scoping and unified responses.
+- When adding async tasks, include tenant/site identifiers and respect Celery limits from settings.

docs/00-SYSTEM/MULTITENANCY.md

@@ -0,0 +1,79 @@
+# Multitenancy Model
+
+## Purpose
+Explain how tenant, site, and sector isolation is enforced across models, middleware, and viewsets, based on the current implementation.
+
+## Code Locations (exact paths)
+- Tenant base models: `backend/igny8_core/auth/models.py` (`AccountBaseModel`, `SiteSectorBaseModel`)
+- Core entities: `backend/igny8_core/auth/models.py` (`Account`, `Plan`, `Site`, `Sector`, `Industry`, `IndustrySector`, `SeedKeyword`, `SiteUserAccess`, `User`)
+- Middleware for context: `backend/igny8_core/auth/middleware.py`
+- DRF base viewsets: `backend/igny8_core/api/base.py`
+- Auth utilities and JWT: `backend/igny8_core/api/authentication.py`, `backend/igny8_core/auth/utils.py`
+- URL routing (module mounting): `backend/igny8_core/urls.py`
+
+## High-Level Responsibilities
+- Enforce per-account isolation for all models carrying an `account` FK.
+- Enforce per-site and per-sector scoping for content models via `SiteSectorBaseModel`.
+- Inject tenant context on every request (session or JWT/API key), then apply scoping in base viewsets.
+- Allow controlled overrides for admins, developers, and system accounts.
+
+## Detailed Behavior
+- `AccountBaseModel` adds an `account` FK plus timestamps and indexes; all tenant-scoped models inherit this to guarantee account linkage.
+- `SiteSectorBaseModel` extends `AccountBaseModel` with `site` and `sector` FKs, indexes on `(account, site, sector)`, and a save hook that sets `account` from `site` and validates that `sector` belongs to the same `site`; raises validation errors on mismatch.
+- `AccountContextMiddleware` sets `request.account` by refreshing the authenticated session user (with account and plan) or by decoding JWT tokens; it rejects requests when account is missing or plan is inactive, returning structured JSON and logging out session users. It skips admin and auth endpoints to avoid interference.
+- JWT authentication (`api/authentication.py`) decodes tokens and sets `request.account` from the token payload; API key authentication sets both `request.account` and `request.site` for WordPress bridge calls.
+- `AccountModelViewSet` auto-filters querysets by `account` when models expose that field. It bypasses filtering for admins/developers/system-account users; otherwise, it uses `request.account` or falls back to the authenticated user’s account. Creates set `account` on save when present.
+- `SiteSectorModelViewSet` extends the above to filter by site/sector if those fields exist, using request query parameters and tenancy context.
+- `User` role helpers (`is_admin_or_developer`, `is_system_account_user`) and account checks gate override behavior.
+- `SiteUserAccess` provides explicit per-site access for non-admin roles; `User.get_accessible_sites` respects system account, developer, owner/admin, and granted access rules.
+
+## Data Structures / Models Involved (no code)
+- `Account`: tenant container with plan, credits, billing fields, status, and retention settings.
+- `Plan`: defines limits (max users/sites/industries/author profiles), credit inclusion, Stripe IDs.
+- `Site`: belongs to an account, optionally an industry; includes status, hosting type, legacy WP fields, and SEO metadata.
+- `Sector`: belongs to a site and industry sector template; enforces account alignment and plan-based max-sector validation.
+- `Industry`, `IndustrySector`, `SeedKeyword`: global reference data not bound to a single account.
+- `SiteUserAccess`: explicit many-to-many grants between users and sites.
+- `User`: links to account with role-based access flags.
+
+## Execution Flow
+- Request enters middleware; `AccountContextMiddleware` determines `request.account` (session or JWT/API key), validating plan status.
+- Viewsets inheriting from `AccountModelViewSet`/`SiteSectorModelViewSet` filter querysets by `account` (and site/sector when present) before pagination/serialization.
+- Object creation sets `account` automatically when the serializer’s model has that field; site/sector-based models validate alignment on save.
+- Admin/developer/system-account users skip account filtering; other users remain constrained.
+
+## Cross-Module Interactions
+- All module viewsets depend on the base viewsets for scoping.
+- Automation, planner, writer, billing, linker, optimizer, publisher, and integration models inherit from the tenancy bases to enforce account/site/sector ownership.
+- API key flows for WordPress set `request.site`, enabling integration-specific logic to run in a site-aware context.
+
+## State Transitions (if applicable)
+- Account status changes (active, suspended, trial, cancelled) and plan activation directly affect access through middleware plan validation.
+- Sector creation enforces plan-based limits for active sectors per site.
+
+## Error Handling
+- Middleware returns JSON errors for missing account or inactive plan, with HTTP 403 or 402 semantics and logs out session users.
+- Base viewsets wrap CRUD operations in unified responses; validation failures or missing objects are returned in structured error payloads.
+- Save-time validation on `SiteSectorBaseModel` and `Sector` raises validation errors when site/sector alignment or plan limits are violated.
+
+## Tenancy Rules
+- Every tenant-scoped model carries `account`; site/sector-aware models carry `site` and `sector` and must align to the same account.
+- Middleware populates `request.account`; base viewsets enforce filtering unless the user is an admin/developer/system-account member.
+- System accounts (`aws-admin`, `default-account`, `default`) and privileged roles can bypass scoping; protected from deletion via guard clauses.
+
+## Billing Rules (if applicable)
+- Middleware requires an active plan before allowing requests (except auth/admin paths). Credits, charges, and plan enforcement are handled in billing modules (documented elsewhere).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery tasks inherit tenant context via payloads supplied by calling viewsets/services; the tenancy bases ensure stored records retain `account`/`site`/`sector`.
+
+## Key Design Considerations
+- Tenancy is enforced as early as middleware to avoid leakage in view logic.
+- Base viewsets centralize scoping and unified responses to reduce duplication across modules.
+- Role-based overrides exist for ops and system accounts; safeguards prevent system account deletion.
+
+## How Developers Should Work With This Module
+- Inherit from `AccountBaseModel` or `SiteSectorBaseModel` for any new tenant/site/sector data models.
+- Inherit viewsets from `AccountModelViewSet` or `SiteSectorModelViewSet` to get automatic scoping and unified responses.
+- Do not bypass `AccountContextMiddleware`; ensure new endpoints live under `/api/v1/*` and rely on the auth stack (API key → JWT → session).
+- Validate that new background tasks carry account/site/sector identifiers so downstream saves remain scoped.

docs/00-SYSTEM/TECH-STACK.md

@@ -0,0 +1,61 @@
+# Tech Stack
+
+## Purpose
+Document the concrete technologies and dependencies in use across backend and frontend as defined in the repository.
+
+## Code Locations (exact paths)
+- Backend dependency manifest: `backend/requirements.txt`
+- Backend settings (framework integration): `backend/igny8_core/settings.py`
+- Frontend dependency manifest: `frontend/package.json`
+- Frontend build tooling: `frontend/vite.config.ts`, `frontend/tsconfig*.json`
+
+## High-Level Responsibilities
+- Backend: Django 5.x with DRF for APIs, Celery for async tasks, Redis for broker/result, PostgreSQL or SQLite for data, drf-spectacular for OpenAPI, Stripe/PayPal configs for billing, WhiteNoise for static serving.
+- Frontend: React 19 with Vite, TypeScript, TailwindCSS, Zustand state, React Router 7, ApexCharts and FullCalendar for UI widgets.
+
+## Detailed Behavior
+- Backend settings wire DRF pagination, filters, authentication (API key, JWT, session, basic), throttling, schema generation, CORS, Celery, logging, and Stripe/PayPal credentials. Static assets are served via WhiteNoise; admin uses Django contrib.
+- `requirements.txt` enumerates runtime libs: Django, gunicorn, psycopg2-binary (PostgreSQL), redis, WhiteNoise, DRF, django-filter, django-cors-headers, PyJWT, requests, Celery, BeautifulSoup4, psutil, docker (for ops scripts), drf-spectacular, and stripe.
+- Frontend `package.json` pins React 19, React Router 7, Zustand 5, Vite 6, TailwindCSS 4, ApexCharts 4, FullCalendar 6, react-dnd, dropzone, lucide/react-heroicons, and testing/tooling (Vitest, Testing Library, ESLint).
+- Build scripts use Vite for dev and production builds, with separate marketing mode; tests via Vitest; lint via ESLint; type-check via `tsc -b`.
+
+## Data Structures / Models Involved (no code)
+- Not applicable; this file tracks technology components rather than domain models.
+
+## Execution Flow
+- Backend runs under Django/DRF with middleware and installed apps per `settings.py`. ASGI/WSGI entrypoints in `igny8_core/asgi.py` and `igny8_core/wsgi.py` (default WSGI via gunicorn).
+- Celery worker/beat use Redis URLs from `settings.py` and respect JSON serialization/time limits.
+- Frontend builds with Vite, consuming environment variables defined via Vite conventions.
+
+## Cross-Module Interactions
+- DRF auth classes depend on PyJWT and custom utilities for token handling.
+- Celery tasks in AI/automation/publishing rely on Redis connectivity and the configured serializer/time limits.
+- Stripe/PayPal keys in settings are consumed by billing modules.
+- Frontend API calls rely on the DRF endpoints exposed in `igny8_core/urls.py`.
+
+## State Transitions (if applicable)
+- Dependency-driven: none beyond the build/runtime phases (install → build → serve).
+
+## Error Handling
+- Backend error handling configured via custom DRF exception handler (enabled by default) and logging setup in `settings.py`.
+- Frontend build/test errors are surfaced through Vite/TypeScript/Vitest/ESLint tooling.
+
+## Tenancy Rules
+- Implemented at runtime by backend middleware and viewsets; the tech stack provides JWT, session, and API key support to carry tenant context.
+
+## Billing Rules (if applicable)
+- Stripe and PayPal keys in `settings.py` enable billing integrations; credit logic is implemented in billing modules (documented elsewhere).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery configured in `settings.py` with Redis broker/backend, JSON serialization, and task limits; beat scheduling persists in `celerybeat-schedule`.
+
+## Key Design Considerations
+- Keep dependency manifests authoritative (`requirements.txt`, `package.json`).
+- Redis is the default async backbone; Postgres is the default DB with SQLite fallback for local/dev.
+- Vite + React 19 selected for fast dev/build; TailwindCSS 4 used for styling; Zustand for state.
+
+## How Developers Should Work With This Module
+- Add backend dependencies to `requirements.txt` and pin versions appropriately; update settings if new middleware/auth is added.
+- Add frontend dependencies to `package.json`; run `npm install` and ensure Vite/TSC builds remain clean.
+- Respect configured auth stack (API key → JWT → session) when adding API clients.
+- Keep CORS and env vars aligned with the domains/ports in use for local and production.

docs/10-BACKEND/MODELS.md

@@ -0,0 +1,110 @@
+# 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.
+

docs/10-BACKEND/OVERVIEW.md

@@ -0,0 +1,82 @@
+# Backend Architecture
+
+## Purpose
+Explain how the backend is structured, wired, and executed across Django/DRF, middleware, routing, async processing, and logging.
+
+## Code Locations (exact paths)
+- Settings and app wiring: `backend/igny8_core/settings.py`
+- URL routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/middleware/resource_tracker.py`
+- Auth stack: `backend/igny8_core/api/authentication.py`, `backend/igny8_core/auth/utils.py`
+- Base viewsets and unified responses: `backend/igny8_core/api/base.py`
+- Domain models: `backend/igny8_core/auth/models.py` plus `backend/igny8_core/business/*/models.py`
+- Async/Celery config: `backend/igny8_core/settings.py`
+- Logging: `backend/igny8_core/settings.py` (publish/webhook logs), automation logging (`backend/igny8_core/business/automation/services/automation_logger.py`)
+
+## High-Level Responsibilities
+- Django/DRF API surface under `/api/v1/*` for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
+- Middleware establishes request IDs, tenant context, and optional resource tracking before views run.
+- DRF configuration standardizes pagination, filtering, authentication, throttling, and exception handling.
+- Celery + Redis provide async execution for AI, automation, publishing, and other long-running tasks.
+- Logging and CORS/security settings are centralized in settings.
+
+## Detailed Behavior
+- Apps registered in `INSTALLED_APPS` include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, publisher. Custom admin config is loaded first.
+- Middleware order: security → WhiteNoise → CORS → session/common/CSRF → Django auth → `RequestIDMiddleware` → `AccountContextMiddleware` (tenant + plan enforcement) → `ResourceTrackingMiddleware` (opt-in for admin/developer with header) → messages → clickjacking.
+- Routing (`urls.py`): admin plus CSV helpers for industries/seed keywords, then `/api/v1/` routers for auth, account, planner, writer, system, billing (user/admin), automation, linker, optimizer, publisher, integration. OpenAPI served at `/api/docs` and `/api/redoc`.
+- DRF defaults: unified exception handler (unless env disables), custom pagination, filtering/search/ordering, auth stack (API key → JWT → CSRF-exempt session → basic), scoped throttling per operation class, drf-spectacular schema generation with tag ordering.
+- CORS: IGNY8 domains and local dev ports allowed; credentials enabled; request/resource tracking headers exposed.
+- Celery: Redis broker/result; JSON serialization; task/soft time limits; single-prefetch; sentinel/SSL toggles via env.
+- Logging: console plus rotating files for publish/sync, WordPress API, webhooks; request IDs from middleware surface in responses; automation has dedicated file-based logger per run.
+
+## Data Structures / Models Involved (no code)
+- Tenancy/identity: `Account`, `Plan`, `Subscription`, `Site`, `Sector`, `User`, `SiteUserAccess`, `PasswordResetToken` (in auth models).
+- Domain models across planner, writer, billing, automation, publishing, integration, optimization (see domain models doc).
+- Middleware uses request-scoped `request.account`, `request.site`, and `request.request_id`.
+
+## Execution Flow
+1) Request enters middleware stack; IDs and tenant context are set; plan is verified.  
+2) DRF auth classes authenticate user/api-key/JWT/session.  
+3) Base viewsets filter by tenant/site/sector and handle unified responses.  
+4) Serializers validate; database writes enforce tenant alignment via model bases.  
+5) Optional Celery tasks are enqueued for long-running work; responses remain synchronous JSON with pagination/throttle headers when applicable.  
+6) Logging writes to configured handlers; request/resource IDs are added to responses.
+
+## Cross-Module Interactions
+- Tenant context from middleware is consumed by all module viewsets.  
+- AI and automation invoke Celery tasks and AI functions; billing services deduct credits used by automation/AI flows.  
+- Integration/publishing modules rely on API key auth to set `request.site` for WordPress and other platforms.
+
+## State Transitions (if applicable)
+- Account/plan validity is checked per request; system accounts are protected from deletion.  
+- Soft-delete is available on many models via `SoftDeletableModel`.  
+- Request lifecycle includes request ID creation, optional resource tracking, and unified response formatting.
+
+## Error Handling
+- Custom DRF exception handler wraps errors with `success=false`.  
+- `AccountContextMiddleware` blocks requests lacking account or active plan (403/402 JSON).  
+- Base viewsets wrap validation/404/500 errors into unified payloads.
+
+## Tenancy Rules
+- Request-level `account` (and `site`/`sector` where applicable) is injected by middleware/auth; base viewsets enforce filtering.  
+- Admin/developer/system-account users bypass tenant filtering; system accounts are guarded from deletion.
+
+## Billing Rules (if applicable)
+- Billing env keys configured in settings; plan enforcement occurs in middleware; credit debits handled by billing services during operations.
+
+## Background Tasks / Schedulers (if applicable)
+- Celery worker/beat use Redis URLs from settings; task limits and JSON serialization enforced.  
+- Automation, AI, publishing, and optimization tasks run async; automation logger writes per-run files.
+
+## Key Design Considerations
+- Middleware-first tenant enforcement ensures isolation.  
+- Unified API standards (responses, throttles, schema) keep clients consistent.  
+- Celery offloads expensive AI/automation/publishing work with bounded execution.  
+- Logging and request IDs aid observability; resource tracking is opt-in for admins.
+
+## How Developers Should Work With This Module
+- Register new apps in `INSTALLED_APPS` and route them under `/api/v1/*`.  
+- Use existing middleware order; add new middleware only if it does not break account/request ID handling.  
+- Inherit from base viewsets for scoping and response consistency.  
+- Use Celery for long-running tasks; respect Redis/task time-limit settings.  
+- Keep env vars (DB, JWT, Redis, Stripe/PayPal) set per `settings.py`; avoid hardcoded secrets.  

docs/10-BACKEND/SERVICES.md

@@ -0,0 +1,96 @@
+# Services and Modules
+
+## Purpose
+Describe the backend service layer and module wiring that orchestrate domain models, AI/automation, billing, integration, and publishing.
+
+## Code Locations (exact paths)
+- Automation services: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`
+- Billing services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+- Integration service: `backend/igny8_core/business/integration/services/integration_service.py`
+- Additional service directories (see module-specific docs for details):
+  - Planner: `backend/igny8_core/business/planning/services/*`
+  - Content/Writer: `backend/igny8_core/business/content/services/*`
+  - Automation tasks: `backend/igny8_core/business/automation/tasks.py`
+  - Integration sync: `backend/igny8_core/business/integration/services/*`
+  - Publishing: `backend/igny8_core/business/publishing/services/*`
+  - Optimization: `backend/igny8_core/business/optimization/services/*`
+  - Linking: `backend/igny8_core/business/linking/services/*`
+
+## High-Level Responsibilities
+- Orchestrate multi-stage automation that chains planner and writer operations using AI and credits.
+- Manage credit pricing, balance checks, deductions, and ledger logging.
+- Generate invoices and handle billing documents.
+- Create, update, test, and list site integrations for external platforms.
+- Provide domain-specific service hooks for planner, writer, publishing, linking, and optimization flows (behavior documented in module-specific files).
+
+## Detailed Behavior
+### Automation
+- `AutomationService` enforces single concurrent run per site via cache lock, estimates required credits, checks account balance (with buffer), and creates an `AutomationRun`. It sequences stages (keywords→clusters, clusters→ideas, ideas→tasks/content, image prompt generation, image generation queue) using AI functions (`AutoClusterFunction`, `GenerateIdeasFunction`, `GenerateContentFunction`, `GenerateImagePromptsFunction`) through `AIEngine`, and the Celery image queue (`process_image_generation_queue`). It supports pause/cancel checks mid-stage, records partial progress, and advances `current_stage` with per-stage result JSON and credit tallies. Batch sizes and delays respect `AutomationConfig`.
+- `AutomationLogger` creates per-run directories (and optional shared mirrors), generates run IDs, writes main/stage logs, mirrors to shared folders when configured, and emits structured JSONL trace events for run start, progress, completion, and errors.
+
+### Billing
+- `CreditService` computes credit cost by first consulting `CreditCostConfig` (unit-aware for words/items/images) and falling back to constants. It checks balances, deducts credits atomically, updates account balance, writes `CreditTransaction`, and logs usage in `CreditUsageLog` with optional model/token metadata. It can also add credits and provides legacy check helpers.
+- `InvoiceService` generates invoice numbers per account/month, creates invoices for subscriptions or credit packages (adding line items and computing totals), supports custom invoices, and marks invoices paid or void. PDF generation is currently a placeholder.
+- `PaymentService` (see file) processes payments against invoices and updates statuses; details are documented in the module file.
+
+### Integration
+- `IntegrationService` creates, updates, deletes, fetches, and lists `SiteIntegration` records, setting account/site automatically. It can test connections per platform (WordPress, Shopify) and delegates to platform-specific test helpers inside the service; unimplemented platforms raise `NotImplementedError`. Credentials are set via `set_credentials`, which currently stores JSON as-is.
+- Additional sync services (`content_sync_service.py`, `sync_service.py`, `sync_metadata_service.py`, `sync_health_service.py`) coordinate publish/sync flows and health checks; see module docs for specifics.
+
+### Other Service Areas (structure)
+- Planner services (`clustering_service.py`, `ideas_service.py`) handle clustering/idea logic.
+- Content services (`content_generation_service.py`, `content_pipeline_service.py`, `metadata_mapping_service.py`, `validation_service.py`) manage content generation, pipelines, metadata mapping, and validation.
+- Publishing services (`publisher_service.py`, `deployment_service.py`, `adapters/`) manage publishing/deployment flows and destination adapters.
+- Optimization services (`analyzer.py`, `optimizer_service.py`) analyze and optimize content.
+- Linking services (`candidate_engine.py`, `injection_engine.py`, `linker_service.py`) prepare and apply link suggestions.
+- Automation tasks (`business/automation/tasks.py`) provide Celery entrypoints for automation runs.
+
+## Execution Flow
+- Automation: `AutomationService.start_automation` acquires lock → credit estimate/check → create `AutomationRun` → stage methods query planner/writer models, call AI functions via `AIEngine`, respect batch sizes/delays, and update run state/logs → credits are tallied from `AITaskLog` differences.
+- Billing: operations call `CreditService.check_*`/`deduct_*` before AI or content operations; invoices are created through `InvoiceService` and payments processed via `PaymentService`.
+- Integration: API endpoints invoke `IntegrationService` to persist integrations, retrieve lists, and run connection tests; sync services handle subsequent data movement.
+- Other domains: planner/content/publishing/linking/optimization services orchestrate their models and, where applicable, AI or external adapters; see domain docs for invocation points.
+
+## Cross-Module Interactions
+- Automation stages consume planner (Keywords/Clusters/ContentIdeas) and writer (Tasks/Content/Images) data and rely on credit usage logs from AI tasks.
+- Billing services are used by automation/AI flows to enforce credit availability and record deductions.
+- Integration services connect site data and publishing/sync flows to external platforms; publishing services depend on integration metadata when targeting destinations.
+- Planner/content services feed data used by publishing and optimization tasks.
+
+## State Transitions (if applicable)
+- Automation runs move through stages, can pause/cancel, and record partial progress with stage result JSON.
+- Credit balances mutate through add/deduct operations; transactions/usage logs capture each change.
+- Invoices progress through draft/pending/paid/void and payments through their status lifecycle.
+- Integrations toggle active/sync flags and update sync status/errors.
+
+## Error Handling
+- Automation: checks for concurrent runs; validates minimum keywords; pauses/cancels mid-stage; writes stage error messages; releases locks on failures.
+- Billing: raises when credit cost unknown or balance insufficient; wraps changes in atomic transactions.
+- Integration: platform test errors are logged and returned with `success=false`; unsupported platforms raise `NotImplementedError`.
+- Invoice service prevents voiding paid invoices and returns placeholder PDF until implemented.
+
+## Tenancy Rules
+- Services operate on tenant-scoped models; constructors typically receive account/site or derive them from models. Integration creation sets account from site; credit operations mutate `Account.credits`.
+- Privileged role bypass applies at the viewset layer; persisted records maintain account/site ownership.
+
+## Billing Rules (if applicable)
+- Costs resolved via `CreditCostConfig` (preferred) or constants; units can be per request, words (100/200), item, or image.
+- Deduct operations both adjust `Account.credits` and log to `CreditTransaction` and `CreditUsageLog`.
+- Invoice creation links to subscriptions or credit packages and uses account billing email/plan pricing.
+
+## Background Tasks / Schedulers (if applicable)
+- Automation uses Celery for image generation and may be triggered by scheduled runs (frequency/time in `AutomationConfig`).
+- Other long-running tasks (publishing, optimization, sync) are handled via their Celery tasks/adapters in respective service modules.
+
+## Key Design Considerations
+- Automation enforces exclusivity per site and accounts for credit sufficiency before starting.
+- Logging (AutomationLogger) produces per-run artifacts and structured traces for observability.
+- Credit handling is centralized to keep ledger and usage logs consistent and atomic.
+- Integration services abstract platform handling and allow per-platform test logic.
+
+## How Developers Should Work With This Module
+- Reuse `AutomationService` for running/continuing automation; respect locks and stage APIs.
+- Use `CreditService` before AI/content-heavy operations to check/deduct/add credits and to log usage.
+- Create invoices via `InvoiceService` helpers rather than constructing manually; update invoice/payment status through service methods.
+- Manage integrations through `IntegrationService` (create/update/test/list) and extend platform-specific tests as needed.
+- For domain-specific flows (planner/content/publishing/linking/optimization), place orchestration in the existing service modules and keep tenant context explicit.

docs/10-BACKEND/automation/AUTOMATION-REFERENCE.md

@@ -0,0 +1,91 @@
+# Automation Module Reference
+
+## Purpose
+Document how the automation module orchestrates multi-stage AI pipelines, exposes API endpoints, enforces tenancy/credits, and manages runs, configs, and logging.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/automation/models.py`
+- Services: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`
+- Tasks (Celery): `backend/igny8_core/business/automation/tasks.py`
+- API views and routing: `backend/igny8_core/business/automation/views.py`, `urls.py`
+- Supporting AI functions: `backend/igny8_core/ai/functions/auto_cluster.py`, `generate_ideas.py`, `generate_content.py`, `generate_image_prompts.py`, image queue in `backend/igny8_core/ai/tasks.py`
+- Tenancy/auth context: `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/api/base.py`
+
+## High-Level Responsibilities
+- Maintain per-site automation configs (batch sizes, delays, schedule, enable flag) and track run state with detailed per-stage results.
+- Provide APIs to configure, trigger, pause/resume/cancel, inspect, and log automation runs.
+- Execute seven sequential stages that transform planner/writer data via AI and local operations, with credit checks and pause/cancel handling.
+- Enforce tenant/site scoping on all automation resources and API operations.
+
+## Detailed Behavior
+- `AutomationConfig` stores enablement, frequency, scheduled time, batch sizes for stages 1–6, and within/between-stage delays. Config is created lazily per site.
+- `AutomationRun` captures run metadata: trigger type (manual/scheduled), status (`running/paused/cancelled/completed/failed`), current stage, pause/cancel timestamps, per-stage JSON results, total credits used, and error message.
+- `AutomationService` orchestrates the pipeline:
+  - Locks per site via cache (`automation_lock_{site.id}`) to prevent concurrent runs.
+  - Estimates credits before start and requires a 20% buffer over the estimate against `Account.credits`.
+  - Creates `AutomationRun` with generated `run_id` and logs start via `AutomationLogger`.
+  - Executes stages in order; each stage logs start/progress/complete, applies within/between-stage delays from config, and writes stage result JSON (counts, credits, timestamps, partial flags).
+  - Pause/cancel checks occur inside loops; state is persisted so resumed runs continue from the recorded stage.
+  - Stage credit usage is derived from AI task logs difference before/after the stage.
+- API layer (`AutomationViewSet`):
+  - `config`/`update_config` read/write `AutomationConfig` for a given `site_id` (scoped to the user’s account).
+  - `run_now` triggers `AutomationService.start_automation` and enqueues Celery `run_automation_task`.
+  - `current_run`, `history`, `logs`, `current_processing`, `estimate`, `pipeline_overview` expose run status, history, logs, credit estimates, and per-stage pending counts.
+  - `pause`, `resume`, `cancel` endpoints update run status and enqueue resume tasks when needed.
+- Celery tasks:
+  - `check_scheduled_automations` scans enabled configs hourly and triggers runs when frequency/time matches and no recent run exists.
+  - `run_automation_task` performs full pipeline execution.
+  - `resume_automation_task`/`continue_automation_task` continue a paused run from its recorded stage.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`, `AutomationRun` (automation state).
+- Planner models: `Keywords`, `Clusters`, `ContentIdeas`.
+- Writer models: `Tasks`, `Content`, `Images`.
+- AI task log (`AITaskLog`) for credit usage measurement.
+- Tenancy entities: `Account`, `Site` (scoping every query).
+
+## Execution Flow
+- API call → DRF auth → tenant/site resolved → viewset method → `AutomationService` operations → Celery task (for long-running execution).
+- Pipeline stages run in-process inside Celery workers, reading planner/writer data, invoking AI functions, updating models, logging progress, and writing stage results to `AutomationRun`.
+- Completion (or failure) updates run status and releases the site lock.
+
+## Cross-Module Interactions
+- Planner/writer models supply inputs and receive outputs (clusters, ideas, tasks, content, images).
+- AI engine executes clustering, idea generation, content generation, and image prompt generation; image rendering uses the AI image queue.
+- Billing credits are checked against `Account.credits`; credit usage is inferred from AI task logs (deduction logic handled in billing services when those AI calls occur).
+- Integration/publishing modules consume content/images produced downstream (outside automation).
+
+## State Transitions
+- Run status moves through `running` → (`paused`/`cancelled`/`failed`/`completed`); `current_stage` increments after each stage finishes; partial flags and timestamps mark mid-stage exits.
+- Config changes take effect on the next run; pause/resume toggles update run timestamps.
+
+## Error Handling
+- Start blocks if a run is already active for the site or cache lock is held.
+- Stage loops log and continue on per-batch/item errors; pause/cancel results are persisted mid-stage.
+- Failures in Celery run mark `AutomationRun` as failed, store error message, timestamp completion, and release the lock.
+- API endpoints return 400 for missing params or invalid state transitions, 404 for unknown runs, 500 on unexpected errors.
+
+## Tenancy Rules
+- All automation queries filter by `site` tied to the authenticated user’s `account`; config/run creation sets `account` and `site` explicitly.
+- API endpoints fetch `Site` with `account=request.user.account`; automation locks are per site.
+- No cross-tenant access; privileged role bypass is handled by DRF auth/permissions upstream.
+
+## Billing Rules
+- Start requires `Account.credits` ≥ 1.2× estimated credits; otherwise a 400 is returned.
+- Credits actually deducted by AI tasks are reflected via AI task logs and billing services (outside this module); automation aggregates usage per stage in `AutomationRun`.
+
+## Background Tasks / Schedulers
+- Hourly `check_scheduled_automations` respects config frequency/time and last run; skips if a run is already active.
+- Pipeline execution and resume steps run inside Celery tasks; within-stage sleeps apply delays from config.
+
+## Key Design Considerations
+- Single-run-per-site enforced via cache lock to prevent overlapping credit use or data contention.
+- Pause/resume/cancel is cooperative, checked inside stage loops, with partial results persisted.
+- Stage-by-stage logging and result JSON make pipeline progress observable and resumable.
+- Configurable batch sizes and delays balance throughput and API/credit usage.
+
+## How Developers Should Work With This Module
+- Use `AutomationService.start_automation` for new runs; never bypass the cache lock or credit check.
+- When extending stages, preserve pause/cancel checks, result recording, and credit delta calculation.
+- Add new API actions through `AutomationViewSet` if they manipulate automation state; keep site/account scoping.
+- For new schedulers, reuse the lock pattern and `AutomationConfig` fields, and update `next_run_at` appropriately.

docs/10-BACKEND/automation/PIPELINE-STAGES.md

@@ -0,0 +1,102 @@
+# Automation Pipeline Stages
+
+## Purpose
+Detail the seven pipeline stages executed by `AutomationService`, including inputs, queries, validations, delays, credit handling, and state recording.
+
+## Code Locations (exact paths)
+- Orchestration: `backend/igny8_core/business/automation/services/automation_service.py`
+- Models: `backend/igny8_core/business/automation/models.py`
+- AI functions: `backend/igny8_core/ai/functions/auto_cluster.py`, `generate_ideas.py`, `generate_content.py`, `generate_image_prompts.py`
+- Image queue: `backend/igny8_core/ai/tasks.py` (`process_image_generation_queue`)
+- Stage entrypoints: `backend/igny8_core/business/automation/tasks.py` (Celery `run_automation_task`, `resume_automation_task`)
+
+## High-Level Responsibilities
+- Execute a fixed seven-stage sequence that moves data from planner keywords through content with images and into manual review readiness.
+- Enforce batch sizes/delays from `AutomationConfig`, support pause/cancel, and write per-stage results into `AutomationRun`.
+- Track credit deltas per stage using AI task log counts.
+
+## Detailed Behavior
+Across all stages:
+- Each stage logs start/progress/complete via `AutomationLogger`, respects `within_stage_delay` between batches/items, and `between_stage_delay` between stages.
+- Pause/cancel is checked inside loops; on pause/cancel, the stage records partial counts, credits, elapsed time, and reason, then exits.
+- Credits used per stage are computed from `AITaskLog` count delta relative to stage start.
+
+### Stage 1: Keywords → Clusters (AI)
+- Input query: `Keywords` where `site=current`, `status='new'`, `cluster__isnull=True`, `disabled=False`.
+- Validation: `validate_minimum_keywords` requires at least 5 keywords; if not valid, stage is skipped with result noting skip reason and `current_stage` advances to 2.
+- Processing: Batch size = `stage_1_batch_size` (capped to total). For each batch, calls `AIEngine.execute(AutoClusterFunction, payload={'ids': batch})`; waits on task ID; logs per-batch progress. Errors are logged and skipped; pipeline continues.
+- Result: counts keywords processed, clusters created since run start, batches, credits used, time elapsed; sets `current_stage=2`.
+
+### Stage 2: Clusters → Ideas (AI)
+- Pre-check: warns if any `Keywords` still pending from Stage 1.
+- Input query: `Clusters` where `site=current`, `status='new'`, `disabled=False`.
+- Processing: Iterates clusters one-by-one; for each, calls `AIEngine.execute(GenerateIdeasFunction, payload={'cluster_id': cluster.id})`; waits on task ID; logs progress. Errors are logged and skipped.
+- Result: counts clusters processed, ideas created since run start, credits used, time elapsed; sets `current_stage=3`.
+
+### Stage 3: Ideas → Tasks (Local)
+- Pre-check: warns if clusters remain without ideas.
+- Input query: `ContentIdeas` where `site=current`, `status='new'`.
+- Processing: Batched by `stage_3_batch_size`. For each idea, builds keyword string (M2M keywords or `target_keywords`) and creates `Tasks` with queued status, copying account/site/sector, cluster, content type/structure, and description. Idea status set to `queued`.
+- Result: ideas processed, tasks created, batches, time elapsed (credits 0 because local); sets `current_stage=4`.
+
+### Stage 4: Tasks → Content (AI)
+- Pre-check: warns if `ContentIdeas` remain `new`.
+- Input query: `Tasks` where `site=current`, `status='queued'`.
+- Processing: Batched by `stage_4_batch_size`. Uses `GenerateContentFunction` via `AIEngine` per batch (payload contains task IDs). Waits on task IDs, logs progress, continues on errors. Tracks total words by summing generated content word_count.
+- Result: tasks processed, content created count, total_words, credits used, time elapsed; sets `current_stage=5`.
+
+### Stage 5: Content → Image Prompts (AI)
+- Input query: `Content` where `site=current`, `status='draft'`, with zero images (annotated count=0).
+- Processing: Batched by `stage_5_batch_size`. For each batch, calls `GenerateImagePromptsFunction` via `AIEngine` (payload content IDs). Waits on task IDs, logs progress; continues on errors.
+- Result: content processed, prompts created (from AI task logs), credits used, time elapsed; sets `current_stage=6`.
+
+### Stage 6: Image Prompts → Images (AI image queue)
+- Input query: `Images` where `site=current`, `status='pending'`.
+- Processing: Iterates pending images; for each, enqueues `process_image_generation_queue.delay(image_ids=[id], account_id, content_id)` when Celery is available, or calls directly in sync fallback. Waits on task IDs with continue-on-error to avoid blocking the stage. Logs progress per image; applies within-stage delay between images.
+- Result: images processed, images generated (status `generated` since run start), content moved to `review`, credits used, time elapsed; sets `current_stage=7`.
+
+### Stage 7: Manual Review Gate (Count-only)
+- Input query: `Content` where `site=current`, `status='review'`.
+- Processing: Counts review-ready content, logs IDs (truncated), marks run `status='completed'`, sets `completed_at`, and releases the site lock.
+- Result: ready_for_review count and content IDs stored in `stage_7_result`.
+
+## Execution Flow
+- Celery task `run_automation_task` instantiates `AutomationService.from_run_id` and calls stages 1→7 sequentially.
+- Stage transitions update `AutomationRun.current_stage`; between-stage delays applied via `between_stage_delay`.
+- Resume path (`resume_automation_task`) starts from the recorded `current_stage` and continues through remaining stages.
+
+## Cross-Module Interactions
+- Planner: Stage 1/2 use `Keywords`/`Clusters`; Stage 3 converts `ContentIdeas` into `Tasks`.
+- Writer: Stages 4–6 create `Content` and `Images` and move content toward review.
+- AI engine and functions are invoked in Stages 1, 2, 4, 5; Stage 6 uses the AI image queue.
+- Billing: Credits are consumed by AI calls; automation records deltas per stage from AI task logs.
+
+## State Transitions
+- `AutomationRun.status` moves to `completed` at Stage 7; can be set to `failed` on exceptions or `cancelled` via API; `paused` can be set mid-run and resumed.
+- `current_stage` increments after each successful stage; partial stage results include a `partial` flag and stop reason.
+- Domain models change status along the pipeline (`Keywords` → clusters, `Clusters` → ideas, `ContentIdeas` → queued/tasks, `Tasks` → completed/content, `Content` → draft/review, `Images` → generated).
+
+## Error Handling
+- Each stage logs errors and continues to next batch/item; pause/cancel checks short-circuit with partial results saved.
+- Task wait helper tolerates Celery backend errors; can continue on error when flagged.
+- Stage start may be skipped with explicit skip reason (e.g., insufficient keywords).
+
+## Tenancy Rules
+- All queries filter by `site` (and implicit account via tenancy bases); account/site set on created `Tasks` and inherited on `Images` and other records through model save hooks.
+- Locks and runs are per site; API scoping requires the authenticated user’s account to own the site.
+
+## Billing Rules
+- Start requires sufficient credits (1.2× estimate). Credits used are inferred from AI task log counts per stage; actual deductions occur in AI/billing services invoked by the AI functions.
+
+## Background Tasks / Schedulers
+- Entire stage chain runs inside Celery workers; within-stage sleeps respect config delays; between-stage sleeps applied after each stage.
+
+## Key Design Considerations
+- Idempotent, resume-capable progression with partial state persisted in `AutomationRun`.
+- Configurable batch sizes/delays mitigate rate limits and manage credit burn.
+- Continue-on-error semantics prevent single failures from stopping the pipeline while still recording issues.
+
+## How Developers Should Work With This Module
+- When modifying stages, keep pause/cancel checks, stage result recording, and credit delta calculation.
+- Add new AI stages by wiring through `AIEngine.execute` and the task wait helper; ensure queries are site-scoped and statuses updated.
+- For new items types, add pending queries and status transitions consistent with existing patterns.

docs/10-BACKEND/automation/SCHEDULER.md

@@ -0,0 +1,75 @@
+# Automation Scheduler
+
+## Purpose
+Describe how scheduled runs are detected, triggered, and resumed using Celery tasks and automation configs.
+
+## Code Locations (exact paths)
+- Celery tasks: `backend/igny8_core/business/automation/tasks.py`
+- Models: `backend/igny8_core/business/automation/models.py`
+- Service invoked: `backend/igny8_core/business/automation/services/automation_service.py`
+
+## High-Level Responsibilities
+- Periodically scan enabled automation configs to start scheduled runs.
+- Prevent overlapping runs per site via cache locks and active run checks.
+- Resume paused runs from their recorded stage.
+
+## Detailed Behavior
+- `check_scheduled_automations` (Celery, hourly):
+  - Iterates `AutomationConfig` with `is_enabled=True`.
+  - Frequency rules:
+    - `daily`: run when current hour matches `scheduled_time.hour`.
+    - `weekly`: run Mondays at the scheduled hour.
+    - `monthly`: run on the 1st of the month at the scheduled hour.
+  - Skips if `last_run_at` is within ~23 hours or if an `AutomationRun` with `status='running'` exists for the site.
+  - On trigger: instantiates `AutomationService(account, site)`, calls `start_automation(trigger_type='scheduled')`, updates `last_run_at` and `next_run_at` (via `_calculate_next_run`), saves config, and enqueues `run_automation_task.delay(run_id)`.
+  - Exceptions are logged per site; lock release is handled by the service on failure paths.
+- `run_automation_task`:
+  - Loads service via `from_run_id`, runs stages 1–7 sequentially.
+  - On exception: marks run failed, records error/completed_at, and deletes site lock.
+- `resume_automation_task` / alias `continue_automation_task`:
+  - Loads service via `from_run_id`, uses `current_stage` to continue remaining stages.
+  - On exception: marks run failed, records error/completed_at.
+- `_calculate_next_run`:
+  - Computes next run datetime based on frequency and `scheduled_time`, resetting seconds/microseconds; handles month rollover for monthly frequency.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`: contains schedule fields (`frequency`, `scheduled_time`, `last_run_at`, `next_run_at`, `is_enabled`).
+- `AutomationRun`: records run status/stage used during resume/failure handling.
+
+## Execution Flow
+1) Celery beat (or cron) invokes `check_scheduled_automations` hourly.  
+2) Eligible configs spawn new runs via `AutomationService.start_automation` (includes lock + credit check).  
+3) `run_automation_task` executes the pipeline asynchronously.  
+4) Paused runs can be resumed by enqueueing `resume_automation_task`/`continue_automation_task`, which restart at `current_stage`.  
+5) Failures set run status to `failed` and release locks.
+
+## Cross-Module Interactions
+- Uses planner/writer data inside the pipeline (see pipeline doc); billing/credits enforced at start.
+- Locking is done via Django cache, independent of other modules but prevents concurrent Celery runs per site.
+
+## State Transitions
+- Config timestamps (`last_run_at`, `next_run_at`) update on scheduled launch.
+- Run status changes to `failed` on task exceptions; to `completed` at stage 7; to `paused/cancelled` via API.
+
+## Error Handling
+- Scheduled start is skipped with log messages if recently run or already running.
+- Exceptions during run execution mark the run failed, record error message, set `completed_at`, and release the cache lock.
+
+## Tenancy Rules
+- Configs and runs are site- and account-scoped; scheduler uses stored account/site from the config; no cross-tenant scheduling.
+
+## Billing Rules
+- Start uses `AutomationService.start_automation`, which enforces credit sufficiency before scheduling the Celery execution.
+
+## Background Tasks / Schedulers
+- Hourly `check_scheduled_automations` plus the long-running `run_automation_task` and resume tasks run in Celery workers.
+
+## Key Design Considerations
+- Hourly scan with coarse matching keeps implementation simple while honoring per-site schedules.
+- Cache lock and active-run checks prevent double-starts from overlapping schedules or manual triggers.
+- Resume task reuses the same stage methods to keep behavior consistent between fresh and resumed runs.
+
+## How Developers Should Work With This Module
+- When adding new frequencies, extend `check_scheduled_automations` and `_calculate_next_run` consistently.
+- Ensure Celery beat (or an equivalent scheduler) runs `check_scheduled_automations` hourly in production.
+- Preserve lock acquisition and failure handling when modifying task flows to avoid orphaned locks.

docs/10-BACKEND/billing/BILLING-REFERENCE.md

@@ -0,0 +1,98 @@
+# Billing Module Reference
+
+## Purpose
+Explain how billing is implemented: invoices, payments, credit packages, credit history/usage, payment methods, and limits, as exposed by billing services and API viewsets.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/billing/models.py`
+- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+- API (business billing): `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/business/billing/urls.py`
+- API (core billing endpoints): `backend/igny8_core/modules/billing/views.py`, `backend/igny8_core/modules/billing/urls.py`
+- Plan metadata (included credits/limits): `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
+
+## High-Level Responsibilities
+- Maintain credit ledger, usage logs, configurable per-operation costs, invoices, payments, credit packages, country-level payment method configs, and account-scoped payment methods.
+- Expose endpoints for invoices/payments/credit packages/transactions, credit balance/usage/limits, and admin billing operations.
+- Deduct or add credits atomically while recording both transactions and usage logs.
+- Provide manual and (placeholder) Stripe/PayPal payment flows.
+
+## Detailed Behavior
+- Invoices (`InvoiceViewSet`):
+  - `list`/`retrieve`: fetch account-scoped invoices; include totals, line items, billing period, dates.
+  - `download_pdf`: returns PDF bytes from `InvoiceService.generate_pdf` (currently placeholder text payload).
+- Payments (`PaymentViewSet`):
+  - `list`: account-scoped payments with amounts, methods, status, invoice linkage, timestamps.
+  - `available_methods`: delegates to `PaymentService.get_available_payment_methods` (country/config-driven; returns methods plus metadata).
+  - `create_manual_payment`: creates a manual payment for an invoice (bank/local wallet); requires invoice_id, method, reference; rejects already-paid invoices; returns pending-approval status.
+- Account payment methods (`AccountPaymentMethodViewSet`):
+  - CRUD for account-level payment metadata (non-sensitive). `perform_create`/`perform_update` enforce one default by resetting others when `is_default` true or none exists.
+  - `set_default` toggles default within the account.
+- Credit packages (`CreditPackageViewSet`):
+  - `list`: active packages with credits/price/discount/featured/sort order.
+  - `purchase`: creates invoice via `InvoiceService.create_credit_package_invoice`; returns next action depending on requested payment method (`stripe`/`paypal` placeholders, manual fallback returns invoice info).
+- Credit transactions (`CreditTransactionViewSet` in business billing views; also registered under `credits/transactions` in URLs): lists credit ledger entries per account.
+- Core billing endpoints (`modules/billing/views.py`):
+  - `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month.
+  - `CreditUsageViewSet`: paginated credit usage logs with filters (operation_type, date range); `summary` aggregates by operation/model and totals (credits, USD); `limits` returns plan/account limits and usage (users/sites/etc.) based on `Plan` fields.
+- Routing (`business/billing/urls.py`):
+  - Routers for invoices, payments, credit packages, transactions, payment methods, and canonical credit endpoints (balance/usage/transactions). Legacy available-methods endpoint exposed at `/payment-methods/available/`.
+
+## Data Structures / Models Involved (no code)
+- `CreditTransaction`: ledger with type, amount (positive/negative), balance_after, metadata.
+- `CreditUsageLog`: per-AI-operation usage with operation_type, credits_used, cost_usd, model_used, tokens, related object references, metadata.
+- `CreditCostConfig`: per-operation cost config with unit, display metadata, active flag, audit of previous cost.
+- `Invoice`: invoice_number, status, amounts (subtotal/tax/total), currency, billing_period, line_items JSON, subscription link, payment metadata, timestamps.
+- `Payment`: status lifecycle, method (stripe/paypal/bank/local wallet/manual), provider references, manual notes/approval, failure reason, metadata.
+- `CreditPackage`, `PaymentMethodConfig` (country/method availability + instructions/bank/local wallet data), `AccountPaymentMethod` (account-scoped payment metadata).
+- Plan/account credits and limits: `Plan.included_credits`, `Plan.max_users/sites/industries/author_profiles`, `Account.credits`.
+
+## Execution Flow
+- Credits:
+  - Operations call `CreditService.get_credit_cost` → `check_credits`/`deduct_credits` or `deduct_credits_for_operation` → updates `Account.credits`, writes `CreditTransaction` and `CreditUsageLog`.
+  - Costs resolved from `CreditCostConfig` when active; otherwise constants. Units support per request, per 100/200 words, per item/image/idea.
+- Invoicing/Payments:
+  - Credit package purchase → invoice creation → next-action response (manual vs pending Stripe/PayPal integration).
+  - Manual payment submission → `PaymentService.create_manual_payment` persists pending approval.
+- Credit balance/usage:
+  - Balance endpoint computes plan credits and month-to-date usage (from `CreditUsageLog`).
+  - Usage endpoint filters logs; summary aggregates by operation/model and totals; limits endpoint computes plan-based limits and usage (users/sites/etc.) per account.
+
+## Cross-Module Interactions
+- AI/automation/planner/writer flows trigger credit checks/deductions through `CreditService`; usage logs can be filtered by operation_type (clustering, idea_generation, content_generation, image_generation, optimization, reparse).
+- Plan limits surfaced in billing limits endpoint affect account/user/site management elsewhere.
+- Invoice/payment metadata may be used by frontend billing UI; manual payments require admin follow-up.
+
+## State Transitions
+- Credits mutate `Account.credits`; ledger captures each change; usage logs accumulate per operation.
+- Invoices move through statuses (`draft/pending/paid/void/uncollectible`); payments through (`pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled`).
+- Credit packages and payment methods have active/default flags; cost configs can be toggled active/inactive.
+
+## Error Handling
+- Insufficient credits raise `InsufficientCreditsError`; API returns 402 when caught (e.g., content generation, credit deduct flows).
+- Manual payment rejects missing fields or already-paid invoices.
+- Usage/balance endpoints return empty data when account/plan missing instead of hard errors.
+- Validation errors on site/sector/account scoping propagate from base viewsets and model constraints.
+
+## Tenancy Rules
+- Account scoping enforced via `AccountModelViewSet` or explicit account filtering in viewsets; all billing data is per-account.
+- Payment methods, invoices, payments, transactions, usage logs, and balances are filtered to `request.user.account` (or `request.account` from middleware).
+- Plan data comes from the account’s associated plan; no cross-tenant visibility.
+
+## Billing Rules
+- Credit costs configurable via `CreditCostConfig`; fallback constants apply when no config.
+- Credit deductions and ledger entries are atomic; usage logs record the same operation with optional model/token metadata.
+- Balance endpoint includes plan monthly credits; limits endpoint reports plan/user/site limits but does not enforce them here.
+
+## Background Tasks / Schedulers
+- None specific to billing in this module; Stripe/PayPal integrations are placeholders. Any future webhooks should persist to these models and adjust credits/invoices/payments accordingly.
+
+## Key Design Considerations
+- Credit handling is centralized in `CreditService` to keep ledger and usage logs consistent.
+- Usage/balance endpoints are read-mostly, with graceful handling when plan/account data is missing.
+- Manual payments support bank/local wallet flows without storing sensitive data; account payment methods store display metadata only.
+
+## How Developers Should Work With This Module
+- Use `CreditService` for all credit checks/deductions/additions; do not mutate `Account.credits` directly.
+- When adding new AI operations, add `operation_type` to `CreditUsageLog.OPERATION_TYPE_CHOICES` and `CreditCostConfig` seed/constants, then use `deduct_credits_for_operation`.
+- Extend payment flows by implementing Stripe/PayPal handlers in `PaymentService` and wiring webhooks to update `Payment`/`Invoice`.
+- Use existing serializers/viewsets when exposing billing data; keep queries scoped to `request.account`.

docs/10-BACKEND/billing/CREDITS-SYSTEM.md

@@ -0,0 +1,80 @@
+# Credit System
+
+## Purpose
+Detail how credits are priced, checked, deducted, logged, and reported across the platform.
+
+## Code Locations (exact paths)
+- Credit logic: `backend/igny8_core/business/billing/services/credit_service.py`
+- Credit costs config: `backend/igny8_core/business/billing/models.py` (`CreditCostConfig`)
+- Ledger and usage logs: `backend/igny8_core/business/billing/models.py` (`CreditTransaction`, `CreditUsageLog`)
+- API endpoints: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`, `CreditUsageViewSet`)
+- Constants and exceptions: `backend/igny8_core/business/billing/constants.py`, `exceptions.py`
+- Plan included credits: `backend/igny8_core/auth/models.py` (`Plan.included_credits`, `Account.credits`)
+
+## High-Level Responsibilities
+- Compute operation costs (configurable per operation and unit) and enforce sufficient balance before AI/content actions.
+- Deduct or add credits atomically while writing both transaction and usage log records.
+- Provide balance, usage history, summaries, and limits endpoints for clients.
+- Allow admin-configurable cost overrides via `CreditCostConfig`.
+
+## Detailed Behavior
+- Cost resolution (`CreditService.get_credit_cost`):
+  - First checks `CreditCostConfig` for the operation (active records). Supports units: `per_request`, `per_100_words`, `per_200_words`, `per_item`, `per_image`. Applies amounts when provided (e.g., words, items, images).
+  - Falls back to hardcoded `CREDIT_COSTS` constants; raises `CreditCalculationError` for unknown operations.
+  - Legacy variable costs: content_generation per 100 words, optimization per 200 words, image_generation per image, idea_generation per idea.
+- Balance enforcement:
+  - `check_credits`/`check_credits_legacy` raise `InsufficientCreditsError` when balance insufficient.
+  - `deduct_credits_for_operation` computes cost, checks balance, builds a default description per operation when not supplied, then calls `deduct_credits`.
+- Deduction (`deduct_credits`):
+  - Atomic: decrements `Account.credits`, writes `CreditTransaction` with negative amount and balance_after, writes `CreditUsageLog` capturing operation_type, cost_usd/model/tokens/related object references, metadata.
+- Add credits (`add_credits`):
+  - Atomic: increments `Account.credits`, writes `CreditTransaction` with positive amount and balance_after.
+- Logging:
+  - `CreditTransaction` is the authoritative ledger; `CreditUsageLog` tracks per-operation usage for analytics and summaries.
+  - `CreditCostConfig` tracks `previous_cost` on save when cost changes.
+- Reporting endpoints (modules/billing):
+  - `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month (from `CreditUsageLog`), and remaining credits.
+  - `CreditUsageViewSet.list`: paginated usage logs filtered by operation_type and date range, account-scoped.
+  - `CreditUsageViewSet.summary`: aggregates credits and USD cost by operation and model over a date range (defaults to current month).
+  - `CreditUsageViewSet.limits`: returns plan limits (users/sites/industries/author profiles) and current usage counts, plus credits info; returns empty limits if account/plan missing.
+
+## Data Structures / Models Involved (no code)
+- `CreditCostConfig`: operation_type, credits_cost, unit, display_name, description, is_active, previous_cost, updated_by, timestamps.
+- `CreditTransaction`: transaction_type (purchase/subscription/refund/deduction/adjustment), amount (+/-), balance_after, description, metadata, reference_id, created_at.
+- `CreditUsageLog`: operation_type (clustering/idea_generation/content_generation/image_generation/reparse/legacy names), credits_used, cost_usd, model_used, tokens_in/out, related object type/id, metadata, created_at.
+- `Account.credits`: current balance; `Plan.included_credits`: monthly included credits.
+
+## Execution Flow
+- Caller requests an operation → `get_credit_cost` computes cost → `check_credits` ensures balance → `deduct_credits` mutates balance and writes ledger + usage → upstream operation proceeds (AI/content).
+- Balance/usage endpoints read from `Account`, `CreditUsageLog`, `Plan` to present current balances, month-to-date usage, summaries, and limits.
+
+## Cross-Module Interactions
+- AI/automation/planner/writer services call `CreditService` before expensive operations; automation aggregates credits used per stage from AI task logs, while billing logs capture actual deductions at AI call sites.
+- Plan limits (users/sites/industries/authors) referenced in billing limits endpoint inform account management elsewhere.
+
+## State Transitions
+- Balance changes recorded per transaction; usage accumulates per operation. Cost configs can be toggled active/inactive and updated with audit of previous cost.
+
+## Error Handling
+- Unknown operation types raise `CreditCalculationError`; insufficient balance raises `InsufficientCreditsError` (mapped to HTTP 402 in callers).
+- Balance/usage endpoints fall back to zeros/empty when account/plan missing rather than erroring.
+
+## Tenancy Rules
+- All credit operations and queries are account-scoped; viewsets filter by `request.account`/`request.user.account`. No cross-tenant access.
+
+## Billing Rules
+- Costs derived from `CreditCostConfig` > constants; units must match supplied amount. Ledger and usage logs are mandatory for every deduction/addition.
+
+## Background Tasks / Schedulers
+- None dedicated; credit usage often originates from AI Celery tasks but logging happens at the service call site.
+
+## Key Design Considerations
+- Centralized credit math and atomic DB updates prevent drift between balance, ledger, and usage logs.
+- Configurable costs allow runtime tuning without code changes.
+- Reporting endpoints are read-only and tolerant of missing plan data to keep dashboards resilient.
+
+## How Developers Should Work With This Module
+- Always route credit checks/deductions/additions through `CreditService`.
+- When adding new AI operations, register operation_type in `CreditUsageLog`/constants and optionally seed `CreditCostConfig`.
+- Include amount (words/items/images) when calling `deduct_credits_for_operation` so unit-based pricing applies.
+- Use balance/usage endpoints for UI/analytics; avoid custom queries that bypass account scoping.

docs/10-BACKEND/planner/PLANNER-REFERENCE.md

@@ -0,0 +1,80 @@
+# Planner Overview
+
+## Purpose
+Explain how the planner module manages keywords, clusters, and content ideas, including tenancy, validation, and API behaviors.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/planning/models.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- URLs: `backend/igny8_core/modules/planner/urls.py`
+- Services: `backend/igny8_core/business/planning/services/clustering_service.py`, `ideas_service.py`
+
+## High-Level Responsibilities
+- Store site/sector-scoped keywords, clusters, and content ideas linked to global seed keywords.
+- Provide CRUD and bulk operations for keywords/clusters/ideas with search, filter, and ordering.
+- Validate industry/sector alignment between seed keywords and site/sector.
+- Feed downstream writer/automation stages with structured ideas and clusters.
+
+## Detailed Behavior
+- Models (site/sector scoped via `SiteSectorBaseModel` and soft-delete):
+  - `Keywords`: references global `SeedKeyword`; optional volume/difficulty overrides; optional cluster; status `new/mapped`; disabled flag; validation ensures seed keyword industry/sector match the site/sector.
+  - `Clusters`: topic groups with counts, volume, mapped_pages, status `new/mapped`; unique per site/sector by name.
+  - `ContentIdeas`: ideas tied to clusters and optional keyword objects; status `new/queued/completed`; content_type/structure and estimated_word_count; disabled flag.
+- Serializers:
+  - `KeywordSerializer` enforces `seed_keyword_id` on create; exposes seed keyword-derived fields (keyword/volume/difficulty/intent) read-only; optional overrides; includes site_id/sector_id write-only; provides cluster/sector names via getters; optional `attribute_values` when `USE_SITE_BUILDER_REFACTOR` flag is enabled.
+  - `ClusterSerializer` exposes site/sector IDs, sector name, read-only counts/volume/mapped_pages.
+  - `ContentIdeasSerializer` exposes cluster/sector names, content type/structure, keyword/target fields, site/sector write-only.
+- Views (`KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet`):
+  - Inherit `SiteSectorModelViewSet` for tenant/site/sector filtering and unified responses.
+  - Permissions: `IsAuthenticatedAndActive` + viewer-or-above (search/list CRUD).
+  - Pagination: `CustomPageNumberPagination`; throttle scope `planner`.
+  - Filters/Search/Ordering: keywords searchable by seed_keyword.keyword; filter by status, cluster_id, seed intent; ordering by created_at, volume, difficulty; custom range filters for difficulty/volume; clusters filter by status; ideas filter by status/cluster.
+  - Creation requires explicit `site_id` and `sector_id`; viewsets validate site/sector existence and alignment; set `account/site/sector` explicitly on save.
+  - Bulk endpoints:
+    - Keywords: `bulk_delete`, two definitions of `bulk_update` (status update) present; `bulk_add_from_seed` to create Keywords from SeedKeywords with site/sector validation.
+    - Clusters: bulk update endpoints in view (not shown above) adjust status.
+    - Ideas: creation and status updates follow standard CRUD; not shown as bulk endpoints in code snippet.
+  - Error handling: viewsets wrap errors into unified responses; return 400/404/500 as appropriate.
+- Services:
+  - `ClusteringService` and `IdeasService` (not detailed here) provide additional business logic for clustering/idea generation when invoked by automation or endpoints.
+
+## Data Structures / Models Involved (no code)
+- `Keywords`, `Clusters`, `ContentIdeas`; global `SeedKeyword`.
+- Tenancy entities: `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → `SiteSectorModelViewSet` filters by account/site/sector → serializers validate seed/site/sector alignment → models persisted → responses returned via unified helpers; bulk actions operate on filtered querysets.
+
+## Cross-Module Interactions
+- Automation stages 1–3 consume planner data (keywords → clusters → ideas → tasks).
+- Writer tasks reference clusters/ideas produced here.
+- Billing credits may be checked upstream for AI clustering/idea generation (via services invoked in automation or planner actions).
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+- Disabled flag can exclude records from processes.
+
+## Error Handling
+- Validation enforces seed/site/sector industry alignment; missing site/sector on create raises validation errors.
+- Bulk operations return 400 on missing IDs/status; general errors return unified 500 responses.
+
+## Tenancy Rules
+- All planner models inherit `SiteSectorBaseModel`; queries are filtered by account/site/sector; admin/developer/system roles can bypass filtering via base viewset logic.
+- Create requires explicit site and sector; viewsets fetch and set account from site/user/middleware.
+
+## Billing Rules
+- None directly in the planner endpoints; credit costs for clustering/idea generation are enforced where those services are called (automation or planner service usage).
+
+## Background Tasks / Schedulers
+- Planner endpoints run synchronously; automation may batch planner data into AI tasks via Celery (documented in automation).
+
+## Key Design Considerations
+- Strict site/sector validation prevents cross-tenant or cross-site leaks.
+- Seed keyword linkage centralizes keyword metadata; overrides allow per-site tuning.
+- Pagination/filtering/search are optimized for large keyword sets.
+
+## How Developers Should Work With This Module
+- Use provided viewsets and serializers; ensure site_id/sector_id are supplied on create.
+- When adding fields, extend serializers with read-only/write-only behavior consistent with current patterns.
+- For new bulk operations, follow existing patterns: validate IDs, operate on filtered queryset, return unified responses.

docs/10-BACKEND/writer/WRITER-REFERENCE.md

@@ -0,0 +1,82 @@
+# Writer Overview
+
+## Purpose
+Describe how the writer module manages tasks, content, images, and taxonomies, including validations, tenancy, and API behaviors.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/content/models.py`
+- Serializers: `backend/igny8_core/modules/writer/serializers.py`
+- Views: `backend/igny8_core/modules/writer/views.py`
+- URLs: `backend/igny8_core/modules/writer/urls.py`
+- Services: `backend/igny8_core/business/content/services/content_generation_service.py`, `validation_service.py`, `metadata_mapping_service.py`
+- Automation linkages: `backend/igny8_core/business/automation/services/automation_service.py` (stages 3–6)
+
+## High-Level Responsibilities
+- Manage tenant/site/sector-scoped tasks, generated/imported content, images, and taxonomies.
+- Provide CRUD and bulk operations for tasks and images; content generation triggers; taxonomy CRUD.
+- Enforce site/sector alignment on creation and propagate account/site/sector to related records.
+- Feed automation and publishing flows with content and images, and integrate with billing credits for AI operations.
+
+## Detailed Behavior
+- Models (all inherit tenant/site/sector bases; many soft-deletable):
+  - `Tasks`: queued work items tied to clusters/ideas/taxonomy; content type/structure; keywords text; word_count target; status `queued/completed`.
+  - `Content`: generated/imported content with HTML, SEO fields, cluster link, content type/structure, taxonomy M2M, external IDs/URLs/metadata, sync status, source (`igny8/wordpress`), status (`draft/review/published`), word_count, timestamps.
+  - `Images`: linked to content or task; auto-sets account/site/sector from provider; tracks type, URL/path, prompt, status, position.
+  - `ContentTaxonomy`: site/sector taxonomy terms (category/tag) with external taxonomy/id, sync status, description, count, metadata; unique per site by slug+type and by external id+taxonomy.
+  - Supporting: `ContentClusterMap`, `ContentAttribute` (documented in domain models).
+- Serializers:
+  - `TasksSerializer`: requires cluster/content_type/content_structure on create; exposes cluster/sector names; write-only site_id/sector_id; defaults status to queued if absent.
+  - `ImagesSerializer`: exposes task/content titles; read-only derived fields; creation requires site/sector (validated, with fallback to request user active site default sector); sets account/site/sector via base perform_create.
+  - `ContentSerializer`: exposes cluster/sector names; taxonomy terms grouped (tags/categories); image status flags; write-only site_id/sector_id; validates presence of required fields and status transitions.
+  - Group serializers for images support grouped responses by content.
+- Views:
+  - `TasksViewSet`: filters/search/order; bulk_delete, bulk_update status; `auto_generate_content` triggers `ContentGenerationService.generate_content` for up to 10 tasks, enforcing account presence and credit checks (returns 402 on `InsufficientCreditsError`); inherits tenant/site/sector filtering.
+  - `ImagesViewSet`: CRUD with ordering/filtering; perform_create enforces site/sector and populates context; `serve_image_file` serves local files with basic checks.
+  - `ContentViewSet`: CRUD for content; ordering/filtering; handles taxonomy assignments; exposes status/SEO fields; uses base scoping.
+  - `ContentTaxonomyViewSet`: CRUD for taxonomy terms (category/tag) scoped to site/sector; inherits base scoping.
+- Services:
+  - `ContentGenerationService`: invoked by `auto_generate_content`; orchestrates AI content generation for tasks, returns async task_id when queued or synchronous result; raises `InsufficientCreditsError` on low balance.
+  - `ContentValidationService`, `MetadataMappingService`: additional processing/validation/mapping (used in writer flows and publishing).
+- Automation linkage:
+  - Stage 3 creates tasks from ideas; Stage 4 generates content; Stage 5 generates image prompts; Stage 6 generates images and moves content to review.
+
+## Data Structures / Models Involved (no code)
+- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, plus `ContentClusterMap`/`ContentAttribute`.
+- Tenancy entities: `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → `SiteSectorModelViewSet` filtering → serializer validation (site/sector required on create) → model save → unified response.
+- `auto_generate_content` validates task IDs/account, calls service → service may enqueue Celery AI tasks or run synchronously → response with task_id or result.
+- Images creation auto-inherits account/site/sector from linked task/content; local file serving bypasses account filter for read-only access.
+
+## Cross-Module Interactions
+- Planner clusters/ideas feed tasks; tasks/content/images feed publishing and automation stages.
+- Billing credits enforced via `ContentGenerationService` when AI is used; automation aggregates credits used per stage from AI task logs.
+- Integration/publishing sync uses content/taxonomy/image data when pushing to external platforms.
+
+## State Transitions
+- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`; Taxonomies created/updated/deleted via CRUD.
+
+## Error Handling
+- Viewsets return unified errors; bulk operations validate IDs/status; `auto_generate_content` returns 400/404/402/500 depending on validation, missing tasks, insufficient credits, or unexpected errors.
+- Images file serving returns 404 on missing file/image.
+
+## Tenancy Rules
+- Base viewset filters enforce account/site/sector scoping; admins/developers/system can bypass filtering; persisted records retain tenant/site/sector ownership.
+- Creation requires site/sector; account set from request/site/user; Images perform_create validates presence of site/sector.
+
+## Billing Rules
+- AI content generation is guarded by credit checks; InsufficientCredits returns HTTP 402; credit logging occurs in billing services at AI call sites.
+
+## Background Tasks / Schedulers
+- AI generation may run via Celery when `ContentGenerationService` returns a task_id; automation stages run inside Celery workers for bulk flows.
+
+## Key Design Considerations
+- Strict site/sector requirements prevent cross-site contamination.
+- Bulk limits (max 10 tasks in auto_generate_content) to control credit burn and processing load.
+- Image serving permits public access via endpoint while still performing existence checks.
+
+## How Developers Should Work With This Module
+- Use existing serializers/viewsets; keep site/sector required on create.
+- When extending AI generation, ensure billing checks (`CreditService`) and account/site scoping are preserved.
+- For new bulk actions, follow current patterns: validate input, operate on filtered queryset, return unified responses.

docs/20-API/API-REFERENCE.md

@@ -0,0 +1,73 @@
+# REST API Reference
+
+## Purpose
+Summarize the major API groups, their base paths, and key actions as implemented in routing and viewsets.
+
+## Code Locations (exact paths)
+- Root routing: `backend/igny8_core/urls.py`
+- Auth endpoints: `backend/igny8_core/auth/urls.py` (APIView + routers)
+- Account management: `backend/igny8_core/api/urls.py`
+- Planner: `backend/igny8_core/modules/planner/urls.py`
+- Writer: `backend/igny8_core/modules/writer/urls.py`
+- System: `backend/igny8_core/modules/system/urls.py`
+- Billing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Automation: `backend/igny8_core/business/automation/urls.py`
+- Integration: `backend/igny8_core/modules/integration/urls.py`
+- Linker/Optimizer/Publisher: respective `modules/*/urls.py`
+
+## High-Level Responsibilities
+- Provide RESTful CRUD endpoints for core resources (auth, planner, writer, billing, automation, integration, etc.) plus custom actions for domain workflows (automation run, billing payments, integration sync, content generation).
+
+## Detailed Behavior (by group)
+- Authentication (`/api/v1/auth/`):
+  - Routers: groups, users, accounts, subscriptions, site-access, plans, sites, sectors, industries, seed-keywords.
+  - APIViews: register, login, change password, refresh token; responses issue JWTs and session login.
+  - CSV admin helpers exposed separately under `/admin/igny8_core_auth/...` for industries/seed keywords.
+- Account management (`/api/v1/account/`):
+  - Settings (`settings/` get/patch), team (`team/` list/create, `team/<id>/` delete), usage analytics (`usage/analytics/`).
+- Planner (`/api/v1/planner/`):
+  - `keywords/`, `clusters/`, `ideas/` (CRUD, filtering/search/ordering, bulk delete/update, bulk add from seed).
+- Writer (`/api/v1/writer/`):
+  - `tasks/`, `images/`, `content/`, `taxonomies/` (CRUD, filtering/search/ordering).
+  - Custom actions: `tasks/auto_generate_content` (AI generation), `tasks/bulk_*`, `images/file`, grouped image utilities; content/taxonomy helpers in viewset.
+- System (`/api/v1/system/`): system settings, prompts, author profiles, etc. (see module docs).
+- Billing (`/api/v1/billing/`):
+  - Invoices (`invoices/`, detail, `download_pdf`), payments (`payments/`, `available_methods`, manual payment), credit packages (`credit-packages/`, purchase), transactions (`transactions/`), payment methods (`payment-methods/`, `set_default`), credits (`credits/balance`, `credits/usage`, `credits/transactions`).
+  - Admin billing under `/api/v1/admin/` (see module billing admin URLs).
+- Automation (`/api/v1/automation/`):
+  - Config (`config`, `update_config`), run (`run_now`), current run, history, logs, estimate, pipeline_overview, current_processing, pause/resume/cancel.
+- Integration (`/api/v1/integration/`):
+  - `integrations/` CRUD, `test_connection`, collection-level `test-connection`, `sync`, `sync_status`, `update-structure`, `get_content_types`, `debug_status`, `sync_wordpress_content`.
+  - Webhooks: `/webhooks/wordpress/status/`, `/webhooks/wordpress/metadata/`.
+- Linker/Optimizer/Publisher: endpoints under `/api/v1/linker/`, `/api/v1/optimizer/`, `/api/v1/publisher/` (viewsets for respective domain resources; see module docs).
+
+## Data Structures / Models Involved (no code)
+- Auth/account models, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images/Taxonomy), billing models (invoices/payments/credits), automation models (runs/configs), integration models (SiteIntegration/SyncEvent), and other module models as routed above.
+
+## Execution Flow
+- Requests hit module routers; viewsets/actions enforce permissions, throttles, and tenancy; serializers map models; responses use unified format.
+
+## Cross-Module Interactions
+- Auth JWTs used by all modules.
+- Billing credits checked in writer/automation flows; billing endpoints expose balances/usage.
+- Integration and publishing rely on writer content; automation depends on planner/writer data.
+
+## State Transitions
+- Managed by respective viewsets (e.g., task status, automation status, invoice/payment status).
+
+## Error Handling
+- Unified error responses; 4xx/5xx codes per viewset logic; throttling per scope.
+
+## Tenancy Rules
+- Base viewsets enforce account/site/sector filtering; API key auth supports WordPress paths; admin/developer/system roles may bypass filters as coded in base viewsets/auth middleware.
+
+## Billing Rules
+- Credits enforced in writer/automation service calls; billing endpoints expose ledger/usage/balance; insufficient credits return 402 where applicable.
+
+## Background Tasks / Schedulers
+- Automation actions enqueue Celery runs; writer content generation may enqueue AI tasks; other modules mostly synchronous.
+
+## Key Design Considerations
+- Consistent `/api/v1/` namespace with per-module routers.
+- OpenAPI schema available at `/api/schema`, Swagger at `/api/docs`, Redoc at `/api/redoc`.
+- Use module docs for endpoint-level details; this file outlines the map of API groups and actions.

docs/20-API/AUTHENTICATION-ENDPOINTS.md

@@ -0,0 +1,62 @@
+# Authentication Endpoints
+
+## Purpose
+Detail authentication-related endpoints for registration, login, password change, token refresh, and auth-adjacent resources (users/accounts/plans/sites/sectors/industries/seed keywords).
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/auth/urls.py`
+- Views: `backend/igny8_core/auth/views.py`
+- Serializers: `backend/igny8_core/auth/serializers.py`
+- Auth utils: `backend/igny8_core/auth/utils.py`
+
+## High-Level Responsibilities
+- Issue JWT access/refresh tokens and session auth on login.
+- Register users, change passwords, refresh tokens.
+- Provide CRUD for users, accounts, subscriptions, site access, plans, sites, sectors, industries, seed keywords via routers.
+
+## Detailed Behavior
+- APIViews:
+  - `POST /api/v1/auth/register/` → `RegisterView`: validates via `RegisterSerializer`, creates user, returns user data.
+  - `POST /api/v1/auth/login/` → `LoginView`: validates credentials, logs in user (session), generates access/refresh JWTs with expiries, returns user data and tokens; 401 on invalid credentials.
+  - `POST /api/v1/auth/change-password/` → `ChangePasswordView`: requires auth, validates old/new passwords, updates password; 400 on invalid current password or validation errors.
+  - `POST /api/v1/auth/refresh/` → `RefreshTokenView`: accepts refresh token, validates, issues new access token with expiry; 401/400 on invalid/expired tokens.
+- Routers under `/api/v1/auth/`:
+  - `groups/`, `users/`, `accounts/`, `subscriptions/`, `site-access/`, `plans/`, `sites/`, `sectors/`, `industries/`, `seed-keywords/` mapped to corresponding viewsets in `auth/views.py`. These use base viewsets with tenant filtering and role checks (see module docs).
+- CSV admin helpers (admin UI, not public API): CSV import/export for industry/industrysector/seedkeyword under `/admin/igny8_core_auth/...`.
+
+## Data Structures / Models Involved (no code)
+- `User`, `Account`, `Plan`, `Site`, `Sector`, `Industry`, `SeedKeyword`, `Subscription`, `SiteUserAccess`, `Group`.
+
+## Execution Flow
+- APIView endpoints use serializers to validate, then issue tokens via auth utils (JWT encode with user_id/account_id, type, exp).
+- Router endpoints inherit base viewsets; AccountContextMiddleware sets `request.account`; JWT/Session auth applied per settings; permissions enforced per viewset.
+
+## Cross-Module Interactions
+- Tokens issued here are required by planner/writer/billing/automation/etc.
+- Account/plan/site data informs tenancy and plan enforcement in middleware and billing limits.
+
+## State Transitions
+- User creation, password changes, session login, token issuance/refresh.
+- CRUD on accounts/sites/sectors/industries/seed keywords via routers.
+
+## Error Handling
+- Unified error responses via helpers; login returns 401 on invalid credentials; refresh returns 401/400 on invalid/expired tokens; validation errors return 400 with field errors.
+
+## Tenancy Rules
+- Login loads user with account+plan; middleware later enforces active plan. Router viewsets inherit account/site/sector filtering where applicable.
+
+## Billing Rules
+- None directly; plan data carried on Account; credits handled elsewhere.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- JWT payload includes user_id, account_id, type, exp/iat; uses `JWT_SECRET_KEY`/`JWT_ALGORITHM` from settings.
+- Session login occurs alongside JWT issuance to support browser-based flows.
+
+## How Developers Should Work With This Module
+- Use provided APIViews for auth; do not handcraft JWTs—use `generate_access_token`/`generate_refresh_token`.
+- When extending auth resources (e.g., new user fields), update serializers and viewsets; keep router paths stable.
+- Maintain unified responses and permission/tenancy checks in viewsets.
+

docs/20-API/AUTOMATION-ENDPOINTS.md

@@ -0,0 +1,65 @@
+# Automation Endpoints
+
+## Purpose
+Describe automation API endpoints that configure, trigger, monitor, and control automation runs.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/automation/urls.py`
+- Views: `backend/igny8_core/business/automation/views.py`
+- Services/Tasks: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`, `backend/igny8_core/business/automation/tasks.py`
+
+## High-Level Responsibilities
+- Expose configuration CRUD (get/update) and operational controls (run, pause, resume, cancel).
+- Provide run history, status, logs, pipeline overview, credit estimate, and current processing state.
+- Enforce site/account scoping and authentication.
+
+## Detailed Behavior
+- Base path: `/api/v1/automation/`
+- Key endpoints (actions on `AutomationViewSet`):
+  - `GET config?site_id=` → get/create `AutomationConfig` for site (includes batch sizes, delays, schedule, flags, last/next run).
+  - `PUT update_config?site_id=` → update config fields (enable, frequency, scheduled_time, batch sizes, delays).
+  - `POST run_now?site_id=` → start a run (checks locks/credits) and enqueue Celery `run_automation_task`.
+  - `GET current_run?site_id=` → current running/paused run details with per-stage results and totals.
+  - `GET history?site_id=` → last 20 runs with status and timestamps.
+  - `GET logs?run_id=&lines=` → tail of automation log file for run.
+  - `GET estimate?site_id=` → estimated credits required plus current balance and sufficiency flag (1.2× buffer).
+  - `GET pipeline_overview?site_id=` → counts/pending by stage across planner/writer models.
+  - `GET current_processing?site_id=&run_id=` → live processing state for active run.
+  - `POST pause?run_id=` / `POST resume?run_id=` / `POST cancel?run_id=` → control run state (pause/resume/cancel).
+- Permissions/tenancy: `IsAuthenticated`; site fetched with `account=request.user.account`; automation lock is per site; `request.account` set by middleware.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`, `AutomationRun`, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images).
+
+## Execution Flow
+- View actions call `AutomationService` to start/control runs; long-running work executed by Celery tasks (`run_automation_task`, `resume_automation_task`).
+- Config updates persist to DB; run state and logs updated as stages progress.
+
+## Cross-Module Interactions
+- Uses planner/writer data for counts and processing; AI functions run inside service; billing credits checked via account balance before start and inferred from AI task logs during execution.
+
+## State Transitions
+- Run status: running ↔ paused → completed/failed/cancelled; `current_stage` advances per stage; per-stage results stored in `AutomationRun`.
+- Config `last_run_at`/`next_run_at` updated on scheduled runs.
+
+## Error Handling
+- Missing site_id/run_id → 400; run not found → 404; insufficient credits or concurrent run → 400; server errors → 500.
+- Logs endpoint 404s when run missing.
+
+## Tenancy Rules
+- All operations scoped to the authenticated user’s account/site; no cross-tenant access; locks are per site.
+
+## Billing Rules
+- Start requires credits ≥ estimated * 1.2; credits consumed by AI tasks are recorded via AI task logs and aggregated per stage.
+
+## Background Tasks / Schedulers
+- Celery tasks for scheduled runs (`check_scheduled_automations`) and pipeline execution/resume.
+
+## Key Design Considerations
+- Cooperative pause/resume/cancel with persisted partial results.
+- Log access via filesystem tail; structured per-stage results stored in DB for quick status reads.
+
+## How Developers Should Work With This Module
+- Trigger runs via `run_now`; avoid bypassing locks/credit checks.
+- Extend actions by reusing `AutomationService` and Celery tasks; keep site scoping and error handling consistent.
+

docs/20-API/BILLING-ENDPOINTS.md

@@ -0,0 +1,77 @@
+# Billing Endpoints
+
+## Purpose
+Detail billing API endpoints for invoices, payments, credit packages, transactions, payment methods, and credit balance/usage.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Views: `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/modules/billing/views.py`
+- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+
+## High-Level Responsibilities
+- Expose billing resources (invoices, payments, credit packages, payment methods, credit transactions).
+- Provide credit balance/usage/limits endpoints.
+- Support manual payment submission and available payment methods lookup.
+
+## Detailed Behavior
+- Base paths:
+  - `/api/v1/billing/` (business billing views via router)
+  - `/api/v1/admin/` (admin billing URLs)
+  - `/api/v1/billing/credits/...` (balance/usage/transactions aliases)
+- Invoice endpoints (`InvoiceViewSet`):
+  - `GET /invoices/` list account invoices (status filter optional).
+  - `GET /invoices/{id}/` invoice detail.
+  - `GET /invoices/{id}/download_pdf/` returns PDF bytes (placeholder).
+- Payment endpoints (`PaymentViewSet`):
+  - `GET /payments/` list payments (status filter optional).
+  - `GET /payment-methods/available/` returns available methods (country/config driven).
+  - `POST /payments/manual/` submit manual payment for an invoice (requires invoice_id, payment_method, transaction_reference; rejects already paid).
+- Account payment methods (`AccountPaymentMethodViewSet`):
+  - CRUD at `/payment-methods/`; `POST /payment-methods/{id}/set_default/` toggles default for the account.
+- Credit packages (`CreditPackageViewSet`):
+  - `GET /credit-packages/` list active packages.
+  - `POST /credit-packages/{id}/purchase/` creates invoice and returns next_action (Stripe/PayPal placeholders; manual fallback returns invoice info).
+- Credit transactions (`CreditTransactionViewSet`):
+  - `GET /transactions/` ledger of credit changes; also registered under `/credits/transactions/`.
+- Credit balance/usage/limits (`modules/billing/views.py`):
+  - `GET /credits/balance/` returns credits, plan monthly credits, month-to-date credits used.
+  - `GET /credits/usage/` returns paginated usage logs with filters; `GET /credits/usage/summary/` aggregates by operation/model and totals; `GET /credits/usage/limits/` returns plan/account limits and usage counts.
+- Permissions/tenancy: authenticated users; account-scoped querysets; viewsets rely on `request.account` or `request.user.account`.
+
+## Data Structures / Models Involved (no code)
+- `Invoice`, `Payment`, `CreditPackage`, `CreditTransaction`, `AccountPaymentMethod`, `PaymentMethodConfig`, `CreditUsageLog`, `CreditCostConfig`, `Account`, `Plan`.
+
+## Execution Flow
+- Router dispatch → viewset → service calls (invoice/payment/credit) → DB updates → unified responses. Balance/usage endpoints compute aggregates on demand.
+
+## Cross-Module Interactions
+- Credit costs/checks used by writer/automation AI flows; balances/usage reflect those deductions.
+- Plan limits surfaced in limits endpoint relate to account management in auth/account domains.
+
+## State Transitions
+- Invoices: draft/pending/paid/void/uncollectible; Payments: pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled; Credits balance changes via transactions.
+
+## Error Handling
+- Manual payment: 400 on missing fields or already-paid invoice.
+- Credit operations: 402 returned by upstream callers on `InsufficientCreditsError`.
+- Balance/usage: returns zeros/empty when account/plan missing.
+
+## Tenancy Rules
+- All billing data filtered by account; no cross-tenant access. Default viewsets inherit account scoping from base classes.
+
+## Billing Rules
+- Credit costs come from `CreditCostConfig` or constants; deductions recorded in ledger + usage logs.
+- Available methods and packages are filtered by active flags/config.
+
+## Background Tasks / Schedulers
+- None specific; Stripe/PayPal integrations are placeholders; any future webhooks should update invoices/payments/credits accordingly.
+
+## Key Design Considerations
+- Ledger + usage logs kept in sync via `CreditService`.
+- Manual payment flow avoids storing sensitive data; account payment methods store metadata only.
+
+## How Developers Should Work With This Module
+- Use `CreditService` for credit math; do not mutate balances directly.
+- Implement Stripe/PayPal flows in `PaymentService` if adding gateways; wire webhooks to update models.
+- Keep account scoping on all queries; reuse existing viewsets for new billing features.
+

docs/20-API/INTEGRATION-ENDPOINTS.md

@@ -0,0 +1,66 @@
+# Integration Endpoints
+
+## Purpose
+Document integration API endpoints for managing site integrations, testing connections, syncing, and handling WordPress webhooks.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/integration/urls.py`
+- Views: `backend/igny8_core/modules/integration/views.py`
+- Webhooks: `backend/igny8_core/modules/integration/webhooks.py`
+- Services: `backend/igny8_core/business/integration/services/*`
+
+## High-Level Responsibilities
+- CRUD for `SiteIntegration` records.
+- Test connections (detail and collection-level), trigger syncs, fetch sync status, update site structure, and sync WordPress content.
+- Expose WordPress webhook endpoints for status/metadata updates.
+
+## Detailed Behavior
+- Base path: `/api/v1/integration/`
+- Viewset: `IntegrationViewSet` (`/integrations/`, inherits `SiteSectorModelViewSet` but overrides queryset to filter by site_id since integrations have site only).
+  - Permissions: `IsAuthenticatedAndActive`, `IsEditorOrAbove`; throttle scope `integration`.
+  - Serializer exposes derived `api_key` (from credentials) and validates WordPress integrations require API key.
+  - Actions:
+    - `test_connection` (detail): calls `IntegrationService.test_connection` on existing integration; returns success/error.
+    - `test_connection_collection` (POST `integrations/test-connection/`, AllowAny): accepts site_id/api_key/site_url; validates site ownership or matching `Site.wp_api_key`; creates integration if missing; tests WordPress connection; deletes integration on failure; returns integration_id on success.
+    - `sync`: triggers `SyncService.sync` (direction metadata/both/to_external/from_external); metadata-only path uses `SyncMetadataService` internally.
+    - `sync_status`: returns sync status from `SyncService`.
+    - `update_site_structure`: updates `config_json.content_types` (post_types/taxonomies, plugin flags, timestamp) from WordPress push payload.
+    - `get_content_types`: returns content type config from integration config.
+    - `debug_status`: returns debug data via `SyncHealthService`.
+    - `sync_wordpress_content`: calls `ContentSyncService.sync_from_wordpress` for a specific content_id.
+- Webhooks:
+  - `/webhooks/wordpress/status/` and `/webhooks/wordpress/metadata/` endpoints for WordPress callbacks (handled in `webhooks.py`).
+
+## Data Structures / Models Involved (no code)
+- `SiteIntegration`, `SyncEvent`, `Site`, `Account`.
+
+## Execution Flow
+- CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls → model updates/sync actions. Collection-level test may create/delete integration based on result. Webhooks call handlers for incoming WordPress events.
+
+## Cross-Module Interactions
+- Integrations used by publishing/sync flows to external platforms; WordPress API key path relies on `Site.wp_api_key` and integration credentials.
+- Sync services interact with writer/planner content for metadata/content sync.
+
+## State Transitions
+- Integration `sync_status/last_sync_at/is_active/sync_enabled` updated by sync/test actions; `SyncEvent` records per-action success/failure with timestamps and IDs.
+
+## Error Handling
+- Invalid site/auth/API key return 403/404/400; unsupported platforms raise `NotImplementedError`; failed collection-level tests delete newly created integrations.
+
+## Tenancy Rules
+- All endpoints scoped to the site/account; queryset filters by site_id and permissions enforce authenticated editor-or-above unless using collection-level API key path.
+
+## Billing Rules
+- None; integration endpoints do not change credits.
+
+## Background Tasks / Schedulers
+- None specific; sync logic executes in service calls (may delegate internally).
+
+## Key Design Considerations
+- Single integration per site+platform; collection-level test supports plugin onboarding with API key.
+- Credentials stored as JSON (encryption pending).
+
+## How Developers Should Work With This Module
+- Use `IntegrationService` for CRUD/test; extend platform support via new test logic and serializer validation.
+- Keep site scoping and API key validation intact for collection-level tests.
+

docs/20-API/PLANNER-ENDPOINTS.md

@@ -0,0 +1,62 @@
+# Planner Endpoints
+
+## Purpose
+Document planner API endpoints for keywords, clusters, and content ideas, including filters, bulk actions, and validation rules.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/planner/urls.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+
+## High-Level Responsibilities
+- CRUD for planner entities scoped by account/site/sector with search, filtering, ordering, and bulk operations.
+- Enforce site/sector requirements and seed keyword alignment on creation.
+
+## Detailed Behavior
+- Base path: `/api/v1/planner/`
+- Viewsets (all inherit `SiteSectorModelViewSet`, scoped by account/site/sector, throttled with scope `planner`, paginated):
+  - `KeywordViewSet` (`/keywords/`):
+    - Search: `seed_keyword__keyword`.
+    - Filters: status, cluster_id, seed_keyword intent/id; custom difficulty_min/max and volume_min/max (uses overrides or seed values).
+    - Ordering: created_at, seed volume/difficulty.
+    - Bulk: `bulk_delete`, `bulk_update` (status), `bulk_add_from_seed` (create Keywords from SeedKeywords after validating site/sector).
+    - Create requires site_id and sector_id; validates site/sector existence and alignment.
+  - `ClusterViewSet` (`/clusters/`):
+    - Filters: status; standard CRUD; site/sector required on create.
+  - `ContentIdeasViewSet` (`/ideas/`):
+    - Filters: status, cluster; standard CRUD; site/sector required on create.
+- Serializers enforce required fields on create (`KeywordSerializer` requires seed_keyword_id; site/sector write-only), expose read-only seed-derived fields and cluster/sector names.
+- Error handling: unified responses; validation errors for missing site/sector/seed; bulk actions return 400 when IDs/status missing.
+
+## Data Structures / Models Involved (no code)
+- `Keywords`, `Clusters`, `ContentIdeas`, `SeedKeyword`, plus `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filters (account/site/sector) → serializer validation → model save → unified response; bulk actions operate on filtered queryset.
+
+## Cross-Module Interactions
+- Feeds automation Stage 1–3 and writer tasks/content generation.
+- Billing credits may be checked upstream when AI clustering/idea generation is invoked.
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+
+## Error Handling
+- Missing required IDs or validation failures return 400; unified 500 on unhandled errors.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector via base viewset; admin/developer/system roles can bypass filtering, but data retains tenant/site/sector fields.
+
+## Billing Rules
+- No direct deductions in these endpoints; AI clustering/idea generation costs enforced where services are called.
+
+## Background Tasks / Schedulers
+- None in planner endpoints; automation handles async flows.
+
+## Key Design Considerations
+- Strict site/sector requirements prevent cross-site contamination.
+- Seed linkage keeps keyword metadata consistent; overrides allow site-specific tuning.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes; extend filters/search/order as needed while respecting base scoping.
+

docs/20-API/WRITER-ENDPOINTS.md

@@ -0,0 +1,68 @@
+# Writer Endpoints
+
+## Purpose
+Document writer API endpoints for tasks, content, images, and taxonomies, including bulk actions and AI content generation triggers.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/writer/urls.py`
+- Views: `backend/igny8_core/modules/writer/views.py`
+- Serializers: `backend/igny8_core/modules/writer/serializers.py`
+- Services: `backend/igny8_core/business/content/services/content_generation_service.py`
+
+## High-Level Responsibilities
+- CRUD for writer entities scoped by account/site/sector.
+- Provide bulk operations and AI content generation for tasks.
+- Manage images and taxonomy terms linked to content/tasks.
+
+## Detailed Behavior
+- Base path: `/api/v1/writer/`
+- Viewsets (inherit `SiteSectorModelViewSet`, throttled `writer`, paginated):
+  - `TasksViewSet` (`/tasks/`):
+    - Filters: status, cluster_id, content_type, content_structure; search title/keywords; ordering by title/created_at/status.
+    - Bulk: `bulk_delete`, `bulk_update` (status).
+    - `auto_generate_content`: accepts task IDs (max 10), requires account, enforces credit checks via `ContentGenerationService`, returns async task_id or synchronous result; 402 on insufficient credits.
+    - Create requires site_id/sector_id; validates site/sector alignment; sets account/site/sector explicitly.
+  - `ImagesViewSet` (`/images/`):
+    - Filters: task_id, content_id, image_type, status; ordering by created_at/position/id.
+    - perform_create enforces site/sector presence (from request or defaults), sets account/site/sector; serves local files via `file` action with existence checks.
+  - `ContentViewSet` (`/content/`):
+    - Filters/order/search defined in viewset (titles, status, etc.); manages taxonomy relationships; exposes status, SEO fields, cluster link, external IDs/URLs.
+  - `ContentTaxonomyViewSet` (`/taxonomies/`):
+    - CRUD for taxonomy terms (category/tag) scoped to site/sector.
+- Serializers enforce required fields on create (e.g., cluster/content_type/content_structure for tasks; site/sector for content) and expose read-only derived fields (cluster/sector names, image/taxonomy info).
+- Error handling: unified responses; validation errors return 400; missing resources return 404; `auto_generate_content` can return 402/500 on credits/other errors.
+
+## Data Structures / Models Involved (no code)
+- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, and related domain models; `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filtering (account/site/sector) → serializer validation → model save → unified response; bulk/AI actions invoke services.
+
+## Cross-Module Interactions
+- Planner clusters/ideas feed tasks; automation stages 3–6 operate on writer data; publishing/integration uses content/taxonomies/images.
+- Billing credits enforced during AI content generation via `ContentGenerationService`.
+
+## State Transitions
+- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`.
+
+## Error Handling
+- Standard unified responses; credit errors mapped to 402 in `auto_generate_content`; file serving returns 404 for missing images.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector; base viewset and permissions enforce access; admin/developer/system may bypass filtering but records retain tenant/site/sector fields.
+
+## Billing Rules
+- AI generation actions check/deduct credits via billing services; other CRUD does not alter credits.
+
+## Background Tasks / Schedulers
+- `auto_generate_content` may enqueue Celery AI tasks when returning task_id; automation uses writer endpoints indirectly via services.
+
+## Key Design Considerations
+- Strict site/sector validation on create; max 10 tasks per auto_generate_content to manage load/credits.
+- Image file serving is permissive but guarded by existence checks.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes.
+- When extending AI flows, keep credit checks and account/site scoping intact.
+- Reuse existing viewsets/serializers for new fields; ensure filters/throttles stay aligned with module scope.
+

docs/30-FRONTEND/COMPONENTS.md

@@ -0,0 +1,76 @@
+# Global UI Components and Providers
+
+## Purpose
+Describe global layout, guards, and utility components/providers used throughout the frontend.
+
+## Code Locations (exact paths)
+- App composition and routing: `frontend/src/App.tsx`
+- Entry/providers: `frontend/src/main.tsx`
+- Layout: `frontend/src/layout/AppLayout.tsx`, `frontend/src/layout/AppSidebar.tsx`, `frontend/src/layout/AppHeader.tsx` (and related layout files)
+- Guards: `frontend/src/components/auth/ProtectedRoute.tsx`, `frontend/src/components/common/ModuleGuard.tsx`
+- Global utilities: `frontend/src/components/common/ScrollToTop.tsx`, `frontend/src/components/common/GlobalErrorDisplay.tsx`, `frontend/src/components/common/LoadingStateMonitor.tsx`, `frontend/src/components/common/ErrorBoundary.tsx`
+- Providers: `frontend/src/context/ThemeContext.tsx`, `frontend/src/context/HeaderMetricsContext.tsx`, `frontend/src/components/ui/toast/ToastContainer.tsx`
+
+## High-Level Responsibilities
+- Wrap the app with error handling, theming, metrics, toasts, and routing.
+- Enforce authentication and module access at the route level.
+- Provide global UI behaviors (scroll reset, error banner, loading monitor).
+- Supply consistent layout (sidebar/header/content) for protected areas.
+
+## Detailed Behavior
+- Providers (`main.tsx`):
+  - `ErrorBoundary` wraps the entire app.
+  - `ThemeProvider` supplies theme context.
+  - `HeaderMetricsProvider` supplies header metrics context.
+  - `ToastProvider` exposes toast notifications.
+  - `BrowserRouter` provides routing; renders `<App />`.
+- Routing shell (`App.tsx`):
+  - `GlobalErrorDisplay` renders global errors; `LoadingStateMonitor` tracks loading states.
+  - `ScrollToTop` resets scroll on route changes.
+  - Public routes: `/signin`, `/signup`.
+  - Protected routes: wrapped in `ProtectedRoute` → `AppLayout`; `ModuleGuard` used per-module.
+  - Lazy-loaded module pages inside routes; ModuleGuard enforces module access flags.
+- Guards:
+  - `ProtectedRoute`: checks `useAuthStore` for authentication; redirects unauthenticated users to sign-in; logs out on failed refresh in App effect.
+  - `ModuleGuard`: gates module pages based on module enable settings/permissions.
+- Layout:
+  - `AppLayout` composes sidebar/header/content; `AppSidebar` uses auth store for user/nav; header components provide top-level actions and metrics.
+- Utilities:
+  - `ScrollToTop` listens to route changes and scrolls to top.
+  - `GlobalErrorDisplay` shows global error banners.
+  - `LoadingStateMonitor` tracks loading indicators globally.
+  - `ToastProvider` supplies toast UI primitives for notifications.
+
+## Data Structures / Models Involved (no code)
+- Context values from theme, header metrics, toast providers; auth state from `authStore`; module enable settings from `settingsStore`.
+
+## Execution Flow
+- App bootstrap wraps providers → routes render → ProtectedRoute checks auth → ModuleGuard checks module access → layout renders with sidebar/header → pages load lazily and fetch data.
+
+## Cross-Module Interactions
+- Auth/module settings drive guards; toasts/errors/loading monitors are available to all pages; layout navigation links modules.
+
+## Error Handling
+- `ErrorBoundary` catches render errors.
+  - `GlobalErrorDisplay` surfaces application-level errors.
+  - `ProtectedRoute` logs out on failed refresh in App effect; unauthorized users are redirected.
+
+## Tenancy Rules
+- Enforced via backend auth and module enable settings; guards rely on auth/module settings to gate access.
+
+## Billing Rules
+- None in UI components; billing info shown in pages that consume billing store/endpoints.
+
+## Background Tasks / Schedulers
+- None; components react to store state and router changes.
+
+## Key Design Considerations
+- Provider stack covers theme, metrics, toasts, error boundary, routing.
+- Guards ensure unauthorized access is blocked at the route level.
+- Global utilities avoid repeated boilerplate for scroll/error/loading behaviors.
+
+## How Developers Should Work With This Module
+- Add new protected pages under `ProtectedRoute` and wrap with `ModuleGuard` when module-scoped.
+- Use existing toast/error/loading utilities instead of duplicating.
+- Keep provider order consistent (ErrorBoundary → Theme/Header/Toast → Router → App).
+

docs/30-FRONTEND/FRONTEND-ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# Frontend Architecture
+
+## Purpose
+Explain the frontend structure, routing, state management, providers, and module organization in the React/Vite app.
+
+## Code Locations (exact paths)
+- Entry: `frontend/src/main.tsx`
+- Root app/routing: `frontend/src/App.tsx`
+- State (Zustand stores): `frontend/src/store/*` (authStore, siteStore, billingStore, settingsStore, onboardingStore, columnVisibilityStore, pageSizeStore)
+- API layer: `frontend/src/api/*` and `frontend/src/services/api.ts`
+- Layout and components: `frontend/src/layout/*`, `frontend/src/components/*`
+- Pages: `frontend/src/pages/*` (modules and settings)
+- Config: `frontend/src/config/*`
+- Styles: `frontend/src/index.css`, `frontend/src/styles/igny8-colors.css`
+
+## High-Level Responsibilities
+- Provide SPA routing with protected routes and module guards.
+- Maintain global state for auth, site context, billing, settings, UI preferences via Zustand.
+- Lazy-load module pages to optimize initial load.
+- Wrap the app with providers for theming, toasts, header metrics, error boundary, and router.
+
+## Detailed Behavior
+- Entry (`main.tsx`):
+  - Imports global styles and vendor CSS (Swiper, Flatpickr).
+  - Wraps the app with `ErrorBoundary`, `ThemeProvider`, `HeaderMetricsProvider`, `ToastProvider`, `BrowserRouter`, then renders `<App />` via React 18 `createRoot`.
+- Routing (`App.tsx`):
+  - Uses `BrowserRouter` (in main) with `<Routes>`/`<Route>` inside App.
+  - Public routes: `/signin`, `/signup`.
+  - Protected routes wrapped by `ProtectedRoute` → `AppLayout`; `ModuleGuard` used per-module.
+  - Default dashboard `/` loads `Dashboard/Home`.
+  - Planner routes redirect `/planner` → `/planner/keywords`; writer routes redirect `/writer` → `/writer/tasks`.
+  - Extensive lazy-loaded pages for Planner, Writer, Automation, Linker, Optimizer, Thinker (system), Billing, Admin, Settings, Sites, Help, Reference, Components, UI elements, etc.
+  - `GlobalErrorDisplay` and `LoadingStateMonitor` mounted globally; `ScrollToTop` for navigation changes.
+  - Auth refresh: on mount, if authenticated with token, calls `refreshUser`; on failure with missing credentials message, ignores; otherwise logs out.
+- State (Zustand examples):
+  - `authStore`: persists user/token/refreshToken; `login`/`register` hit `/api/v1/auth/...`; enforces account and active plan presence; `refreshUser` fetches user from `/api/v1/auth/users/me/`; `refreshToken` hits `/api/v1/auth/refresh/`; logout clears all auth fields.
+  - `siteStore`: stores current site/sector and list; used for context across modules.
+  - `billingStore`, `settingsStore`, `onboardingStore`, `columnVisibilityStore`, `pageSizeStore`: manage billing data, settings flags, onboarding steps, table visibility, pagination sizes.
+- API layer:
+  - `services/api.ts` provides `fetchAPI` helper for authenticated calls (uses token from auth store, handles JSON, throws on non-OK).
+  - `api/*` modules define typed client calls per domain (auth, planner, writer, etc.).
+- Layout/components:
+  - `AppLayout` wraps sidebar/header/content; `ModuleGuard` enforces module access flags; `ProtectedRoute` enforces auth.
+  - UI utilities: toasts, error boundary, global loading monitor, scroll-to-top, etc.
+
+## Data Structures / Models Involved (no code)
+- Frontend state shapes defined in Zustand stores (auth user, site context, billing info, settings).
+
+## Execution Flow
+- App bootstrap → providers → App routes → ProtectedRoute checks auth → ModuleGuard checks module access → lazy-loaded pages fetch data via `api/*` using tokens from authStore → state updates via stores.
+
+## Cross-Module Interactions
+- Auth store tokens used by fetchAPI for all modules.
+  - Site store context influences planner/writer/automation calls.
+  - Billing store interacts with billing endpoints; settings store influences UI/features; onboarding/table stores affect page rendering.
+
+## State Transitions
+- Auth: login/register → set user/token; refresh → update tokens/user; logout clears.
+- Site context changes update current site/sector for downstream calls.
+- Billing/settings/onboarding/table state mutate via respective store actions.
+
+## Error Handling
+- `GlobalErrorDisplay` shows errors; `LoadingStateMonitor` tracks loading; `ProtectedRoute` logs out on failed refresh.
+- `fetchAPI` throws on non-OK; authStore catches and surfaces messages; ModuleGuard/ProtectedRoute handle unauthorized access.
+
+## Tenancy Rules
+- Enforced via tokens and site context; ModuleGuard and ProtectedRoute rely on backend responses (account/plan) and module flags.
+
+## Billing Rules
+- Auth store enforces active plan on login; billing store/pages call billing endpoints for balances/transactions/purchases.
+
+## Background Tasks / Schedulers
+- None on frontend; relies on backend/Celery for async work; uses Suspense for lazy loading.
+
+## Key Design Considerations
+- Lazy-loaded routes minimize initial bundle.
+- Zustand persistence keeps auth/session across reloads.
+- Providers wrap app for theming, toasts, error boundary to improve UX stability.
+
+## How Developers Should Work With This Module
+- Add routes inside `App.tsx` under ProtectedRoute for authenticated pages; use ModuleGuard for module-gated pages.
+- Create new stores in `src/store` for shared state; use `fetchAPI` for authenticated requests.
+- Keep lazy loading for heavy pages and maintain Suspense fallbacks where needed.
+

docs/30-FRONTEND/GLOBAL-UI-COMPONENTS.md

@@ -0,0 +1,76 @@
+# Global UI Components and Providers
+
+## Purpose
+Describe global layout, guards, and utility components/providers used throughout the frontend.
+
+## Code Locations (exact paths)
+- App composition and routing: `frontend/src/App.tsx`
+- Entry/providers: `frontend/src/main.tsx`
+- Layout: `frontend/src/layout/AppLayout.tsx`, `frontend/src/layout/AppSidebar.tsx`, `frontend/src/layout/AppHeader.tsx` (and related layout files)
+- Guards: `frontend/src/components/auth/ProtectedRoute.tsx`, `frontend/src/components/common/ModuleGuard.tsx`
+- Global utilities: `frontend/src/components/common/ScrollToTop.tsx`, `frontend/src/components/common/GlobalErrorDisplay.tsx`, `frontend/src/components/common/LoadingStateMonitor.tsx`, `frontend/src/components/common/ErrorBoundary.tsx`
+- Providers: `frontend/src/context/ThemeContext.tsx`, `frontend/src/context/HeaderMetricsContext.tsx`, `frontend/src/components/ui/toast/ToastContainer.tsx`
+
+## High-Level Responsibilities
+- Wrap the app with error handling, theming, metrics, toasts, and routing.
+- Enforce authentication and module access at the route level.
+- Provide global UI behaviors (scroll reset, error banner, loading monitor).
+- Supply consistent layout (sidebar/header/content) for protected areas.
+
+## Detailed Behavior
+- Providers (`main.tsx`):
+  - `ErrorBoundary` wraps the entire app.
+  - `ThemeProvider` supplies theme context.
+  - `HeaderMetricsProvider` supplies header metrics context.
+  - `ToastProvider` exposes toast notifications.
+  - `BrowserRouter` provides routing; renders `<App />`.
+- Routing shell (`App.tsx`):
+  - `GlobalErrorDisplay` renders global errors; `LoadingStateMonitor` tracks loading states.
+  - `ScrollToTop` resets scroll on route changes.
+  - Public routes: `/signin`, `/signup`.
+  - Protected routes: wrapped in `ProtectedRoute` → `AppLayout`; `ModuleGuard` used per-module.
+  - Lazy-loaded module pages inside routes; ModuleGuard enforces module access flags.
+- Guards:
+  - `ProtectedRoute`: checks `useAuthStore` for authentication; redirects unauthenticated users to sign-in; logs out on failed refresh in App effect.
+  - `ModuleGuard`: gates module pages based on module enable settings/permissions.
+- Layout:
+  - `AppLayout` composes sidebar/header/content; `AppSidebar` uses auth store for user/nav; header components provide top-level actions and metrics.
+- Utilities:
+  - `ScrollToTop` listens to route changes and scrolls to top.
+  - `GlobalErrorDisplay` shows global error banners.
+  - `LoadingStateMonitor` tracks loading indicators globally.
+  - `ToastProvider` supplies toast UI primitives for notifications.
+
+## Data Structures / Models Involved (no code)
+- Context values from theme, header metrics, toast providers; auth state from `authStore`; module enable settings from `settingsStore`.
+
+## Execution Flow
+- App bootstrap wraps providers → routes render → ProtectedRoute checks auth → ModuleGuard checks module access → layout renders with sidebar/header → pages load lazily and fetch data.
+
+## Cross-Module Interactions
+- Auth/module settings drive guards; toasts/errors/loading monitors are available to all pages; layout navigation links modules.
+
+## Error Handling
+- `ErrorBoundary` catches render errors.
+  - `GlobalErrorDisplay` surfaces application-level errors.
+  - `ProtectedRoute` logs out on failed refresh in App effect; unauthorized users are redirected.
+
+## Tenancy Rules
+- Enforced via backend auth and module enable settings; guards rely on auth/module settings to gate access.
+
+## Billing Rules
+- None in UI components; billing info shown in pages that consume billing store/endpoints.
+
+## Background Tasks / Schedulers
+- None; components react to store state and router changes.
+
+## Key Design Considerations
+- Provider stack covers theme, metrics, toasts, error boundary, routing.
+- Guards ensure unauthorized access is blocked at the route level.
+- Global utilities avoid repeated boilerplate for scroll/error/loading behaviors.
+
+## How Developers Should Work With This Module
+- Add new protected pages under `ProtectedRoute` and wrap with `ModuleGuard` when module-scoped.
+- Use existing toast/error/loading utilities instead of duplicating.
+- Keep provider order consistent (ErrorBoundary → Theme/Header/Toast → Router → App).
+

docs/30-FRONTEND/STATE-MANAGEMENT.md

@@ -0,0 +1,90 @@
+# State Management
+
+## Purpose
+Describe how the frontend manages global state with Zustand stores, including authentication, site context, billing, and settings.
+
+## Code Locations (exact paths)
+- Auth store: `frontend/src/store/authStore.ts`
+- Site store: `frontend/src/store/siteStore.ts`
+- Billing store: `frontend/src/store/billingStore.ts`
+- Settings store: `frontend/src/store/settingsStore.ts`
+- Other UI/state stores: `frontend/src/store/onboardingStore.ts`, `columnVisibilityStore.ts`, `pageSizeStore.ts`, `settingsStore.ts`, etc.
+
+## High-Level Responsibilities
+- Persist authentication state (user, tokens), refresh sessions, and enforce account/plan presence.
+- Track the active site (and sector via sector store) across modules, with persistence and change events.
+- Fetch and cache billing balances/usage/limits.
+- Load and update account/module settings with coalesced fetches and persistence.
+
+## Detailed Behavior
+- `authStore`:
+  - Persists `user`, `token`, `refreshToken`, `isAuthenticated`, `loading`.
+  - `login(email,password)`: POST `/api/v1/auth/login/`; stores tokens/user; errors mapped to PLAN_REQUIRED/ACCOUNT_REQUIRED/AUTH_FAILED; resets loading on error.
+  - `register(data)`: POST `/api/v1/auth/register/`; stores tokens/user; resets loading on error.
+  - `refreshToken()`: POST `/api/v1/auth/refresh/`; updates access token; attempts `refreshUser`; logs out on failure.
+  - `refreshUser()`: GET `/api/v1/auth/users/me/`; requires account+plan; updates user or logs out on auth failure; clears loading guard.
+  - `logout()`: clears all auth fields.
+- `siteStore`:
+  - Persists `activeSite`; stores `loading`/`error`.
+  - `setActiveSite(site)`: sets/persists site, dispatches `siteChanged` event, triggers sector store load for the site.
+  - `loadActiveSite()`: fetches sites via `fetchSites`; picks prior site if still active, else first active; persists selection.
+  - `refreshActiveSite()`: refreshes current site from server; reloads if inactive/missing.
+- `billingStore`:
+  - Holds `balance`, `usageSummary`, `usageLimits`, `loading`/`error`, `lastUpdated`.
+  - `loadBalance()`: calls `getCreditBalance`; keeps prior balance during retry; sets `lastUpdated`.
+  - `loadUsageSummary(startDate?, endDate?)`: calls `getCreditUsageSummary`; updates summary.
+  - `loadUsageLimits()`: calls `getCreditUsageLimits`; tolerates 404 by returning null; records errors otherwise.
+  - `reset()`: clears billing state.
+- `settingsStore`:
+  - Persists `accountSettings`, `moduleSettings`, `moduleEnableSettings`, `loading`/`error`.
+  - Account settings: load all, load one, create/update with create/update endpoints; handles typed errors (not found vs validation).
+  - Module settings: load/update per module; stores per-module map.
+  - Module enable settings: caches for 60s, coalesces concurrent fetches; `isModuleEnabled` helper.
+  - `reset()` clears settings state.
+- Other stores:
+  - `onboardingStore`, `columnVisibilityStore`, `pageSizeStore` manage UI/onboarding/table preferences (see respective files for exact fields/actions).
+
+## Data Structures / Models Involved (no code)
+- Store state interfaces defined in each file (auth user shape, site, billing balance/usage, settings maps).
+
+## Execution Flow
+- Components/hooks read/write state via `useXStore` hooks.
+- Auth flows call store actions, which perform fetches and update state; ProtectedRoute/ModuleGuard rely on auth and settings/module enable flags.
+- Site changes dispatch `siteChanged` for downstream listeners and trigger sector loading.
+- Billing/settings loads fetch data on demand and cache/persist where configured.
+
+## Cross-Module Interactions
+- Auth tokens consumed by `fetchAPI` for all API calls.
+- Active site influences planner/writer/automation calls via query params/context.
+- Module enable settings influence `ModuleGuard`.
+- Billing data feeds billing pages and credit displays.
+
+## State Transitions
+- Auth: unauthenticated → login/register → authenticated; refresh updates tokens/user; logout clears.
+- Site: load/refresh/set updates `activeSite` and notifies listeners.
+- Billing/settings: load/update actions mutate cached maps and loading/error flags.
+
+## Error Handling
+- Auth store resets loading on all error paths; throws descriptive errors.
+- Billing store tolerates missing limits (404) and surfaces messages; balance retry preserves prior state.
+- Settings store differentiates not-found vs validation errors; stores messages in `error`.
+
+## Tenancy Rules
+- Auth store requires account+plan; site store filters on accessible sites; billing/settings calls use authenticated endpoints tied to the user’s account.
+
+## Billing Rules
+- Enforced via backend; billing store reads balances/usage/limits and does not mutate credits.
+
+## Background Tasks / Schedulers
+- None; all store actions are user-driven fetches with immediate state updates.
+
+## Key Design Considerations
+- Zustand `persist` used for auth/site/settings to survive reloads.
+- Guarded loading flags and error handling prevent stuck states.
+- Site changes broadcast events for dependent components/stores.
+
+## How Developers Should Work With This Module
+- Use existing store actions for auth/site/billing/settings instead of duplicating fetch logic.
+- When adding new shared state, create a dedicated store in `src/store` and persist only needed slices.
+- Keep error/reset semantics consistent (always clear loading on failure).
+

docs/30-FRONTEND/automation/AUTOMATION-UI.md

@@ -0,0 +1,149 @@
+# Automation Frontend Module
+
+**Location:** `frontend/src/pages/automation/`  
+**Purpose:** UI components and pages for automation module
+
+## Source Files
+
+ # Automation Page (AI Automation Pipeline Dashboard)
+ 
+ ## Purpose
+ Provide a site-scoped dashboard to configure, run, pause, resume, and monitor the 7-stage automation pipeline. Surfaces pipeline overview, current run status, metrics, history, configuration modal, and credit sufficiency checks.
+ 
+ ## Code Locations (exact paths)
+ - Primary page: `frontend/src/pages/Automation/AutomationPage.tsx`
+ - Service: `frontend/src/services/automationService` (config, current run, estimate, pipeline overview, runNow, pause, resume, publishWithoutReview)
+ - Metrics sources: `frontend/src/services/api` (`fetchKeywords`, `fetchClusters`, `fetchContentIdeas`, `fetchTasks`, `fetchContent`, `fetchContentImages`)
+ - UI components: `frontend/src/components/Automation/{ActivityLog,ConfigModal,RunHistory,CurrentProcessingCard}`, `frontend/src/components/dashboard/EnhancedMetricCard`, `frontend/src/components/common/ComponentCard`, `frontend/src/components/common/PageMeta`, `frontend/src/components/common/DebugSiteSelector`
+ 
+ ## High-Level Responsibilities
+ - Load automation config, current run, credit estimate, and pipeline overview for the active site.
+ - Poll current run and pipeline status while running/paused; refresh metrics regularly during runs.
+ - Provide controls: Run Now, Pause, Resume, Save Config, Publish Without Review.
+ - Show per-stage cards, current processing card, run history, and activity log.
+ 
+ ## Detailed Behavior
+ - Site binding: requires `useSiteStore.activeSite`; without it, page shows a “select a site” message.
+ - Initial load (`loadData`): parallel calls to `getConfig`, `getCurrentRun`, `estimate`, `getPipelineOverview` plus low-level metrics (keywords/clusters/ideas/tasks/content/images counts) per site_id.
+ - Polling: 5s interval; if run status is `running`/`paused`, refresh run, pipeline, and metrics; otherwise refresh pipeline only.
+ - Metrics: counts for keywords (total/new/mapped), clusters (total/new/mapped), ideas (total/new/queued/completed), tasks (total), content (total/draft/review/published), images (total/pending).
+ - Stage cards: derived from `STAGE_CONFIG` array representing 7 pipeline stages including manual review gate.
+ - Actions:
+   - Run Now: checks credit sufficiency from `estimate`; blocks if insufficient.
+   - Pause/Resume: call automationService with site + run_id, then refresh run/pipeline/metrics.
+   - Save Config: persists partial config, updates local state, reloads pipeline/metrics/run.
+   - Publish Without Review: calls `publishWithoutReview` with confirmation prompt, then reloads.
+ - UI states: `loading` spinner until initial fetch; `showProcessingCard` toggled on when a run exists.
+ 
+ ## Data Structures / Models Involved (no code)
+ - `AutomationConfig`: site-level automation settings (intervals, gates, etc.).
+ - `AutomationRun`: run_id, status (`running`, `paused`, etc.), stage info.
+ - `PipelineStage`: stage list with status/progress.
+ - Metrics DTOs from planner/writer/image endpoints (`count` fields only).
+ 
+ ## Execution Flow
+ - `useEffect` with site dependency → `loadData`.
+ - Interval polling while active runs → `loadCurrentRun`, `loadPipelineOverview`, `loadMetrics`.
+ - User actions dispatch to automationService; toasts for success/error; follow-up refreshes.
+ 
+ ## Cross-Module Interactions
+ - Pulls planner/writer/image counts to present authoritative pipeline context.
+ - Uses `useSiteStore` for tenant/site scoping; credit checks rely on billing estimate API.
+ 
+ ## State Transitions
+ - `currentRun.status` drives polling and control availability.
+ - `showProcessingCard` turns on when a run exists.
+ - `estimate.sufficient` gates Run Now action.
+ 
+ ## Error Handling
+ - Toast-based error reporting; fetch failures log to console but keep page usable.
+ - Metrics fetch wrapped in try/catch; failure degrades to missing metrics without blocking the rest.
+ 
+ ## Tenancy Rules
+ - All automation service calls require `activeSite.id`; backend enforces account/site scoping. No client override for other tenants.
+ 
+ ## Billing Rules (if applicable)
+ - Run Now is blocked when `estimate.sufficient` is false; shows required vs current credits.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Client-side polling (5s) during active runs; no background scheduling beyond that.
+ 
+ ## Key Design Considerations
+ - Polling keeps UI aligned with long-running Celery pipeline states.
+ - Credit gate prevents user-initiated runs that would immediately fail server-side.
+ - Metrics are read-only mirrors of backend aggregates to align UI with planner/writer state.
+ 
+ ## How Developers Should Work With This Module
+ - When adding new stages, extend `STAGE_CONFIG` and ensure backend pipeline overview includes them.
+ - Keep polling interval modest; if adding heavier metrics, consider staggering fetches to avoid rate limits.
+ - Wire new config fields through `AutomationConfig` type, `ConfigModal`, and `updateConfig` payload.
+ # Automation Components
+ 
+ ## Purpose
+ Describe the reusable UI components that compose the automation dashboard: stage cards, current processing card, run history, activity log, and configuration modal. These components visualize pipeline state, history, and settings sourced from automation services.
+ 
+ ## Code Locations (exact paths)
+ - Stage cards & layout: `frontend/src/pages/Automation/AutomationPage.tsx` (renders stage cards from `STAGE_CONFIG`)
+ - Current run card: `frontend/src/components/Automation/CurrentProcessingCard.tsx`
+ - Activity log: `frontend/src/components/Automation/ActivityLog.tsx`
+ - Run history: `frontend/src/components/Automation/RunHistory.tsx`
+ - Config modal: `frontend/src/components/Automation/ConfigModal.tsx`
+ - Shared UI: `frontend/src/components/common/{ComponentCard,PageMeta,DebugSiteSelector}`, `frontend/src/components/dashboard/EnhancedMetricCard`
+ 
+ ## High-Level Responsibilities
+ - Stage cards: show each of the 7 pipeline stages with icon/color/status derived from pipeline overview.
+ - CurrentProcessingCard: surface active run details, stage name, status, percent, timestamps, and controls (Pause/Resume).
+ - ActivityLog: list recent automation events (from run log feed).
+ - RunHistory: show prior runs with status and timestamps.
+ - ConfigModal: edit and persist automation configuration per site.
+ 
+ ## Detailed Behavior
+ - Stage Cards:
+   - Built from `STAGE_CONFIG` array (keywords→clusters, clusters→ideas, ideas→tasks, tasks→content, content→image prompts, image prompts→images, manual review).
+   - Status/progress comes from `pipelineOverview.stages` provided by `automationService.getPipelineOverview`.
+ - CurrentProcessingCard:
+   - Receives `currentRun` and shows status; displays pause/resume buttons wired to page handlers that call `automationService.pause/resume`.
+   - Hidden when no current run; toggled by `showProcessingCard`.
+ - RunHistory:
+   - Takes run list (from `automationService.getCurrentRun` payload history) and renders chronological entries.
+ - ActivityLog:
+   - Displays textual log entries for the active run; consumes run log data supplied by the page.
+ - ConfigModal:
+   - Opens from page button; on save calls `automationService.updateConfig(activeSite.id, newConfig)`; merges into local config and refreshes pipeline/metrics.
+ 
+ ## Data Structures / Models Involved (no code)
+ - `AutomationRun` (id, status, stage, progress, started_at/ended_at).
+ - `PipelineStage` array with stage identifiers, names, progress.
+ - `AutomationConfig` fields shown in modal (intervals/gates/etc., defined server-side).
+ 
+ ## Execution Flow
+ - Page loads run + pipeline → passes data into stage cards, processing card, history, activity log.
+ - User opens ConfigModal → submit triggers updateConfig → page reloads pipeline/metrics/run to reflect new settings.
+ - Pause/Resume buttons on CurrentProcessingCard call page handlers, which in turn call automationService.
+ 
+ ## Cross-Module Interactions
+ - Components depend on site context from `useSiteStore` and data from automationService; no direct planner/writer calls (metrics happen in page).
+ 
+ ## State Transitions
+ - Components are pure renderers; state (visibility, selected config) managed by `AutomationPage`.
+ 
+ ## Error Handling
+ - Errors in save/pause/resume are surfaced by the page via toasts; components render based on provided props.
+ 
+ ## Tenancy Rules
+ - All data passed in is already scoped to `activeSite`; components do not alter scoping.
+ 
+ ## Billing Rules (if applicable)
+ - None inside components; Run Now credit gating handled at page level.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None; updates driven by page polling interval.
+ 
+ ## Key Design Considerations
+ - Separation of concerns: components stay presentational; network calls remain in page.
+ - Stage cards use color/icon metadata for fast visual scanning of pipeline status.
+ 
+ ## How Developers Should Work With This Module
+ - Add new stages by extending `STAGE_CONFIG` and ensuring pipeline overview includes the new stage id/status.
+ - Extend ConfigModal fields in sync with backend `AutomationConfig`; persist via automationService.
+ - Keep CurrentProcessingCard controls minimal; any new action should call automationService and refresh run/pipeline afterward.

docs/30-FRONTEND/writer/WRITER-UI.md

@@ -0,0 +1,183 @@
+# Writer Frontend Module
+
+**Location:** `frontend/src/pages/writer/`  
+**Purpose:** UI components and pages for writer module
+
+## Source Files
+
+ # Writer Main Page (Queue/Drafts/Images Navigation)
+ 
+ ## Purpose
+ Serve as the entry surface for writer workflows, routing users to task queue, drafts, images, review, and published content views. It relies on shared table templates and writer navigation tabs defined in the content/tasks/images pages.
+ 
+ ## Code Locations (exact paths)
+ - Key pages under Writer:
+   - Tasks (queue): `frontend/src/pages/Writer/Tasks.tsx`
+   - Content drafts/list: `frontend/src/pages/Writer/Content.tsx`
+   - Images: `frontend/src/pages/Writer/Images.tsx`
+   - Content view: `frontend/src/pages/Writer/ContentView.tsx`
+ - Navigation tabs defined inside Tasks/Content/Images pages (`writerTabs`).
+ 
+ ## High-Level Responsibilities
+ - Present writer-specific navigation and headers.
+ - Delegate to module pages that implement task creation, AI generation, content listing, and image management.
+ 
+ ## Detailed Behavior
+ - Writer pages use shared navigation tabs (`writerTabs`: Queue, Drafts, Images, Review, Published) rendered via `ModuleNavigationTabs`.
+ - Each page sets a header (`PageHeader`) with badge icon and binds to the tab component for consistent navigation.
+ - State (filters, pagination, selections) is managed within each page; there is no global writer-state container beyond shared stores (`useSectorStore`, `usePageSizeStore`).
+ 
+ ## Data Structures / Models Involved (no code)
+ - Task, Content, ContentImage DTOs from `frontend/src/services/api` (writer endpoints).
+ 
+ ## Execution Flow
+ - User enters writer area via route (e.g., `/writer/tasks` or `/writer/content`).
+ - Navigation tabs switch routes; each route mounts its page and fetches data (tasks/content/images).
+ 
+ ## Cross-Module Interactions
+ - Sector/site scoping via `useSectorStore` and backend query params in API calls.
+ - Optimization and image generation actions route into optimizer or image generation APIs.
+ 
+ ## State Transitions
+ - Per-page loading/filters; navigation changes unmount current page and mount target page.
+ 
+ ## Error Handling
+ - Each page uses toasts for API errors; no shared error surface beyond per-page banners.
+ 
+ ## Tenancy Rules
+ - Backend filters by account/site/sector; pages pass sector context via filters or rely on server defaults.
+ 
+ ## Billing Rules (if applicable)
+ - None on navigation; individual actions (AI generation) consume credits on backend.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None at the navigation level.
+ 
+ ## Key Design Considerations
+ - Tabs keep writer UX consistent; each page owns its data loading to avoid cross-coupling.
+ 
+ ## How Developers Should Work With This Module
+ - When adding a new writer view (e.g., “Outlines”), add a tab entry and a route in `App.tsx`, and implement the page with the same header/tab pattern.
+ # Image Editor Page (Images List & Generation)
+ 
+ ## Purpose
+ Manage generated images linked to writer content: list images grouped by content, filter/search, trigger generation, update statuses, and download/view images. Uses table template patterns similar to content/tasks.
+ 
+ ## Code Locations (exact paths)
+ - Page: `frontend/src/pages/Writer/Images.tsx`
+ - API: `frontend/src/services/api` (`fetchContentImages`, `fetchImageGenerationSettings`, `generateImages`, `bulkUpdateImagesStatus`, `deleteContent`, `bulkDeleteContent`)
+ - Config: `frontend/src/config/pages/images.config` (columns/filters)
+ - UI components: `frontend/src/components/common/ImageQueueModal`, `frontend/src/components/common/SingleRecordStatusUpdateModal`, `frontend/src/components/common/PageHeader`, `frontend/src/components/navigation/ModuleNavigationTabs`, `frontend/src/components/ui/modal`
+ - Hooks: `frontend/src/hooks/useResourceDebug` (AI logs toggle), `frontend/src/hooks/useProgressModal` (via modal usage pattern)
+ 
+ ## High-Level Responsibilities
+ - Fetch and render content-image groups with client-side filtering/search/sorting/pagination.
+ - Trigger image generation for selected content with queue modal and provider/model selection.
+ - Update image status in bulk and delete images/content.
+ - Provide AI function log visibility when resource debug is enabled.
+ 
+ ## Detailed Behavior
+ - Data load: `loadImages` calls `fetchContentImages({})`, applies client-side search (`content_title`) and status filter (`overall_status`), sorts (default `content_title`), paginates client-side (page size 10), and adds `id` field mirroring `content_id` for selection.
+ - Filters: search text; status dropdown; sort controls; pagination tracked in local state.
+ - Actions:
+   - Generate images: opens `ImageQueueModal`, builds queue items, calls `generateImages` with provider/model; tracks taskId/model/provider state; shows AI logs when resource debug enabled.
+   - Bulk status update: `bulkUpdateImagesStatus` on selected ids.
+   - Delete (single/bulk): uses `deleteContent`/`bulkDeleteContent`.
+   - Download/view: handled by row actions in config (template-driven).
+ - Navigation: writer tabs rendered via `ModuleNavigationTabs` (Queue/Drafts/Images/Review/Published).
+ - Resource debug: AI logs captured only when `useResourceDebug` returns true; `addAiLog` appends logs for visibility.
+ - Loading UX: `loading` + `showContent` gating; debounced search resets page as needed.
+ 
+ ## Data Structures / Models Involved (no code)
+ - `ContentImagesGroup`: content_id, content_title, overall_status, images[].
+ - `ContentImage`: individual image entries with URL/status/prompt (from API).
+ - Generation settings: provider/model options from `fetchImageGenerationSettings`.
+ 
+ ## Execution Flow
+ - `useEffect` → `loadImages`.
+ - Filters/sort/page changes → recompute client-side subsets.
+ - Generate action → open modal → call `generateImages` → optionally log steps → reload images.
+ - Status update/delete actions → call API → reload.
+ 
+ ## Cross-Module Interactions
+ - Tied to writer content records; delete actions use writer content endpoints.
+ - AI generation leverages shared API endpoints that consume credits server-side.
+ 
+ ## State Transitions
+ - `loading`/`showContent` manage render timing; modal open states for queue/status/image viewer.
+ - `aiLogs` maintained only when debug is enabled.
+ 
+ ## Error Handling
+ - Toast errors for load/generate/update/delete; generation errors also recorded in AI logs when enabled.
+ - Debounced search handles errors gracefully by keeping prior data until reload.
+ 
+ ## Tenancy Rules
+ - Backend enforces account/site/sector; client passes no explicit tenant fields beyond any default filters in API layer.
+ 
+ ## Billing Rules (if applicable)
+ - Image generation consumes credits on backend; page performs no credit gating.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None; generation is user-triggered, and polling is not used here.
+ 
+ ## Key Design Considerations
+ - Client-side pagination used because API returns grouped images; keeps UI responsive without extra endpoints.
+ - Resource debug toggle avoids unnecessary log storage unless explicitly enabled.
+ 
+ ## How Developers Should Work With This Module
+ - If server adds server-side pagination/filtering, remove client-side slicing and pass filters to API.
+ - Extend row actions by updating `images.config` with handlers wired to new behaviors.
+ - Keep generation flow in sync with backend provider/model options; surface credit estimates if backend exposes them.
+ # Content Editor Page
+ 
+ ## Purpose
+ Display a single content record with full details for review/read-only inspection. Acts as the per-record viewer for content generated or managed by the Writer module.
+ 
+ ## Code Locations (exact paths)
+ - Page: `frontend/src/pages/Writer/ContentView.tsx`
+ - Template: `frontend/src/templates/ContentViewTemplate` (renders the actual layout/content fields)
+ - API: `frontend/src/services/api` (`fetchContentById`)
+ 
+ ## High-Level Responsibilities
+ - Fetch a specific content item by id from route param and render it via `ContentViewTemplate`.
+ - Validate id parameter, handle not-found/error states, and provide back navigation to content list.
+ 
+ ## Detailed Behavior
+ - Route: `/writer/content/:id`.
+ - On mount: validates `id` is numeric; on invalid, shows toast and redirects to `/writer/content`.
+ - Fetches content via `fetchContentById(contentId)`; sets `content` state and clears `loading`.
+ - Errors: shows toast (`Failed to load content`) and leaves `content` null.
+ - Back action: `onBack` navigates to `/writer/content`.
+ - Page metadata: sets document title/description via `PageMeta`.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Content DTO from writer API (includes title, body/html, status, external_url, etc.; structure defined server-side).
+ 
+ ## Execution Flow
+ - `useEffect` → validate id → fetch content → update state → render template.
+ - Template receives `{ content, loading, onBack }`.
+ 
+ ## Cross-Module Interactions
+ - Navigation back to writer drafts list; no direct cross-module calls.
+ 
+ ## State Transitions
+ - `loading` toggles during fetch; `content` set on success; invalid id triggers navigation away.
+ 
+ ## Error Handling
+ - Toast errors for missing/invalid id or fetch failure; console logs errors.
+ 
+ ## Tenancy Rules
+ - Backend enforces account/site/sector scoping; client only supplies id from route.
+ 
+ ## Billing Rules (if applicable)
+ - None within this view; generation/updates handled elsewhere.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None.
+ 
+ ## Key Design Considerations
+ - Strict id validation avoids bad requests.
+ - Keeps view read-only; editing handled elsewhere (not in this component).
+ 
+ ## How Developers Should Work With This Module
+ - If adding inline editing, extend `ContentViewTemplate` and add PATCH/PUT calls; keep id validation and error handling intact.

docs/40-WORKFLOWS/AUTOMATION-WORKFLOW.md

@@ -0,0 +1,148 @@
+# Automation Module (Code-Sourced, Dec 2025)
+
+Single canonical reference for IGNY8 automation (backend, frontend, and runtime behavior). Replaces all prior automation docs in this folder.
+
+---
+
+## 1) What Automation Does
+- Runs the 7-stage pipeline across Planner/Writer:
+  1) Keywords → Clusters (AI)
+  2) Clusters → Ideas (AI)
+  3) Ideas → Tasks (Local)
+  4) Tasks → Content (AI)
+  5) Content → Image Prompts (AI)
+  6) Image Prompts → Images (AI)
+  7) Manual Review Gate (Manual)
+- Per-site, per-account isolation. One run at a time per site; guarded by cache lock `automation_lock_{site_id}`.
+- Scheduling via Celery beat (`automation.check_scheduled_automations`); execution via Celery tasks (`run_automation_task`, `resume_automation_task` / `continue_automation_task`).
+
+---
+
+## 2) Backend API (behavior + payloads)
+Base: `/api/v1/automation/` (auth required; site must belong to user’s account).
+
+- `GET config?site_id=`: returns or creates config with enable flag, frequency (`daily|weekly|monthly`), scheduled_time, stage_1..6 batch sizes, delays (`within_stage_delay`, `between_stage_delay`), last_run_at, next_run_at.
+- `PUT update_config?site_id=`: same fields as above, updates in-place.
+- `POST run_now?site_id=`: starts a manual run; enqueues `run_automation_task`. Fails if a run is already active or lock exists.
+- `GET current_run?site_id=`: current running/paused run with status, current_stage, totals, and stage_1..7_result blobs (counts, credits, partial flags, skip reasons).
+- `GET pipeline_overview?site_id=`: per-stage status counts and “pending” numbers for UI cards.
+- `GET current_processing?site_id=&run_id=`: live processing snapshot for an active run; null if not running.
+- `POST pause|resume|cancel?site_id=&run_id=`: pause after current item; resume from saved `current_stage`; cancel after current item and stamp cancelled_at/completed_at.
+- `GET history?site_id=`: last 20 runs (id, status, trigger, timestamps, total_credits_used, current_stage).
+- `GET logs?run_id=&lines=100`: tail of the per-run activity log written by AutomationLogger.
+- `GET estimate?site_id=`: estimated_credits, current_balance, sufficient (balance >= 1.2x estimate).
+
+Error behaviors:
+- Missing site_id/run_id → 400.
+- Site not in account → 404.
+- Run not found → 404 on run-specific endpoints.
+- Already running / lock held → 400 on run_now.
+
+---
+
+## 3) Data Model (runtime state)
+- `AutomationConfig` (one per site): enable flag, schedule (frequency, time), batch sizes per stage (1–6), delays (within-stage, between-stage), last_run_at, next_run_at.
+- `AutomationRun`: run_id, trigger_type (manual/scheduled), status (running/paused/cancelled/completed/failed), current_stage, timestamps (start/pause/resume/cancel/complete), total_credits_used, per-stage result JSON (stage_1_result … stage_7_result), error_message.
+- Activity logs: one file per run via AutomationLogger; streamed through the `logs` endpoint.
+
+---
+
+## 4) How Execution Works (AutomationService)
+- Start: grabs cache lock `automation_lock_{site_id}`, estimates credits, enforces 1.2x balance check, creates AutomationRun and log file.
+- AI functions used: Stage 1 `AutoClusterFunction`; Stage 2 `GenerateIdeasFunction`; Stage 4 `GenerateContentFunction`; Stage 5 `GenerateImagePromptsFunction`; Stage 6 uses `process_image_generation_queue` (not the partial `generate_images` AI function).
+- Stage flow (per code):
+  - Stage 1 Keywords → Clusters: require ≥5 keywords (validate_minimum_keywords); batch by config; AIEngine clustering; records keywords_processed, clusters_created, batches, credits, time; skips if insufficient keywords.
+  - Stage 2 Clusters → Ideas: batch by config; AIEngine ideas; records ideas_created.
+  - Stage 3 Ideas → Tasks: local conversion of queued ideas to tasks; batches by config; no AI.
+  - Stage 4 Tasks → Content: batch by config; AIEngine content; records content count + word totals.
+  - Stage 5 Content → Image Prompts: batch by config; AIEngine image-prompts into Images (featured + in-article).
+  - Stage 6 Image Prompts → Images: uses `process_image_generation_queue` with provider/model from IntegrationSettings; updates Images status.
+  - Stage 7 Manual Review Gate: marks ready-for-review counts; no AI.
+- Control: each stage checks `_check_should_stop` (paused/cancelled); saves partial progress (counts, credits) before returning; resume continues from `current_stage`.
+- Credits: upfront estimate check (1.2x buffer) before starting; AIEngine per-call pre-checks and post-SAVE deductions; `total_credits_used` accumulates.
+- Locks: acquired on start; cleared on completion or failure; also cleared on fatal errors in tasks.
+- Errors: any unhandled exception marks run failed, sets error_message, logs error, clears lock; pipeline_overview/history reflect status.
+- Stage result fields (persisted):
+  - S1: keywords_processed, clusters_created, batches_run, credits_used, skipped/partial flags, time_elapsed.
+  - S2: clusters_processed, ideas_created, batches_run, credits_used.
+  - S3: ideas_processed, tasks_created, batches_run.
+  - S4: tasks_processed, content_created, total_words, batches_run, credits_used.
+  - S5: content_processed, prompts_created, batches_run, credits_used.
+  - S6: images_processed, images_generated, batches_run.
+  - S7: ready_for_review counts.
+
+Batching & delays:
+- Configurable per site; stage_1..6 batch sizes control how many items per batch; `within_stage_delay` pauses between batches; `between_stage_delay` between stages.
+
+Scheduling:
+- `check_scheduled_automations` runs hourly; respects frequency/time and last_run_at (~23h guard); skips if a run is active; sets next_run_at; starts `run_automation_task`.
+
+Celery execution:
+- `run_automation_task` runs stages 1→7 sequentially for a run_id; failures mark run failed and clear lock.
+- `resume_automation_task` / `continue_automation_task` continue from saved `current_stage`.
+- Workers need access to cache (locks) and IntegrationSettings (models/providers).
+
+Image pipeline specifics:
+- Stage 5 writes prompts to Images (featured + ordered in-article).
+- Stage 6 generates images via queue helper; AI `generate_images` remains partial/broken and is not used by automation.
+
+---
+
+## 5) Frontend Behavior (AutomationPage)
+- Route: `/automation`.
+- What the user can do: run now, pause, resume, cancel; edit config (enable/schedule, batch sizes, delays); view activity log; view history; watch live processing card and pipeline cards update.
+- Polling: every ~5s while a run is running/paused for current_run, pipeline_overview, metrics, current_processing; lighter polling when idle.
+- Metrics: fetched via low-level endpoints (keywords/clusters/ideas/tasks/content/images) for authoritative counts.
+- States shown: running, paused, cancelled, failed, completed; processing card shown when a run exists; pipeline cards use “pending” counts from pipeline_overview.
+- Activity log: pulled from `logs` endpoint; shown in UI for live tailing.
+
+---
+
+## 6) Configuration & Dependencies
+- Needs IntegrationSettings for AI models and image providers (OpenAI/runware).
+- Requires Celery beat and workers; cache backend required for locks.
+- Tenant scoping everywhere: site + account filtering on all automation queries.
+
+---
+
+## 7) Known Limitations and Gaps
+- `generate_images` AI function is partial/broken; automation uses queue helper instead.
+- Pause/Cancel stop after the current item; no mid-item abort.
+- Batch defaults are conservative (e.g., stage_2=1, stage_4=1); tune per site for throughput.
+- Stage 7 is manual; no automated review step.
+- No automated test suite observed for automation pipeline (stage transitions, pause/resume/cancel, scheduling guards, credit estimation/deduction).
+- Enhancements to consider: fix or replace `generate_images`; add mid-item abort; surface lock status/owner; broaden batch defaults after validation; add operator-facing doc in app; add tests.
+
+---
+
+## 8) Field/Behavior Quick Tables
+
+### Pipeline “pending” definitions (pipeline_overview)
+- Stage 1: Keywords with status `new`, cluster is null, not disabled.
+- Stage 2: Clusters status `new`, not disabled, with no ideas.
+- Stage 3: ContentIdeas status `new`.
+- Stage 4: Tasks status `queued`.
+- Stage 5: Content status `draft` with zero images.
+- Stage 6: Images status `pending`.
+- Stage 7: Content status `review`.
+
+### Stage result fields (stored on AutomationRun)
+- S1: keywords_processed, clusters_created, batches_run, credits_used, skipped, partial, time_elapsed.
+- S2: clusters_processed, ideas_created, batches_run, credits_used.
+- S3: ideas_processed, tasks_created, batches_run.
+- S4: tasks_processed, content_created, total_words, batches_run, credits_used.
+- S5: content_processed, prompts_created, batches_run, credits_used.
+- S6: images_processed, images_generated, batches_run.
+- S7: ready_for_review.
+
+### Credit handling
+- Pre-run: estimate_credits * 1.2 vs account.credits (fails if insufficient).
+- Per AI call: AIEngine pre-check credits; post-SAVE deduction with cost/tokens tracked; total_credits_used aggregates deductions.
+
+### Logging
+- Per-run log file via AutomationLogger; accessed with `GET logs?run_id=&lines=`; includes stage start/progress/errors and batch info.
+
+### Polling (frontend)
+- Active run: ~5s cadence for current_run, pipeline_overview, metrics, current_processing, logs tail.
+- Idle: lighter polling (current_run/pipeline_overview) to show readiness and pending counts.
+

docs/40-WORKFLOWS/CONTENT-LIFECYCLE.md

@@ -0,0 +1,73 @@
+ # Content Lifecycle
+ 
+ ## Purpose
+ Trace content from keyword intake through clustering, idea generation, task creation, AI writing, image generation, and publishing/sync, mapping to backend services and frontend pages.
+ 
+ ## Code Locations (exact paths)
+ - Planner models: `backend/igny8_core/business/planning/models.py` (`Keywords`, `Clusters`, `ContentIdeas`)
+ - Writer models: `backend/igny8_core/business/content/models.py` (`Tasks`, `Content`, `Images`, `ContentTaxonomy`)
+ - ViewSets: `backend/igny8_core/modules/planner/views.py`; `backend/igny8_core/modules/writer/views.py`
+ - Automation orchestration: `backend/igny8_core/business/automation/services/automation_service.py`; Celery tasks `business/automation/tasks.py`
+ - WordPress sync/publish: `backend/igny8_core/business/integration/services/integration_service.py`, `modules/integration/views.py`
+ - Frontend pages: `frontend/src/pages/Planner/*`, `frontend/src/pages/Writer/*`, `frontend/src/pages/Automation/AutomationPage.tsx`, `frontend/src/pages/Sites/*`
+ 
+ ## High-Level Responsibilities
+ - Collect and cluster keywords, generate ideas, create tasks, generate content and images, then publish/sync.
+ - Support manual steps via Planner/Writer pages and automated runs via Automation pipeline.
+ - Maintain site/sector scoping and credit enforcement throughout AI operations.
+ 
+ ## Detailed Behavior
+ - Keywords → Clusters: `KeywordViewSet` (upload/create) and `ClusterViewSet` (manual or AI auto_cluster). Models inherit `SiteSectorBaseModel` for scoping.
+ - Clusters → ContentIdeas: `ContentIdeasViewSet` with AI generation endpoint; ideas track status.
+ - Ideas/Tasks: `Tasks` model holds brief/keywords/structure/status; created manually or by automation stage.
+ - Tasks → Content: Writer endpoints generate content (AI) and update `Content` records; statuses managed in writer views.
+ - Content → Images: `ImagesViewSet` handles image generation and storage; images linked to tasks/content.
+ - Publishing: Integration service sends content to WordPress via `/api/v1/integration` endpoints; WP plugin responds with IDs and syncs status back.
+ - Automation: `automation_service.run_automation` executes 7 stages with delays/retries/credit estimates; run status tracked in `AutomationRun`.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Planner: `Keywords`, `Clusters`, `ContentIdeas`.
+ - Writer: `Tasks`, `Content`, `Images`, `ContentTaxonomy`.
+ - Automation: `AutomationConfig`, `AutomationRun`.
+ - Integration: `SiteIntegration`.
+ 
+ ## Execution Flow
+ - Manual path: upload keywords → cluster (auto/manual) → generate ideas → create tasks → generate content → generate images → publish to WP → WP syncs status back.
+ - Automated path: Automation pipeline stages perform the same transitions in sequence, logging progress and deducting credits.
+ - Each stage uses DRF viewsets; automation uses Celery tasks (`run_automation_task`, `resume_automation_task`) and logger for trace files.
+ 
+ ## Cross-Module Interactions
+ - Automation consumes planner/writer endpoints and triggers integration publish.
+ - Integration relies on site’s WP API key (`Site.wp_api_key`) and `SiteIntegration` config for credentials/URLs.
+ - Billing deducts credits for AI operations through `CreditService`.
+ 
+ ## State Transitions (if applicable)
+ - Keywords: status (active/inactive/used) per model.
+ - Clusters: status (active/archived).
+ - ContentIdeas: status (draft/approved/in_progress/completed).
+ - Tasks: status simplified (queued/completed) in Stage 1; content status (draft/published) and image status stored on related models.
+ - AutomationRun: status across run lifecycle (created/running/paused/completed/failed).
+ 
+ ## Error Handling
+ - Viewsets rely on unified DRF error responses; automation logger records failures per stage; Celery retries configured where applicable.
+ - WordPress sync errors surfaced via integration service responses.
+ 
+ ## Tenancy Rules
+ - All planner/writer/automation/integration models inherit account/site/sector via base models; viewsets filter by `request.account` and query params.
+ 
+ ## Billing Rules (if applicable)
+ - AI clustering/idea/content/image generation deduct credits via `CreditService` cost map; automation blocks run if estimated credits insufficient.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Automation scheduler: `check_scheduled_automations` enqueues runs; `run_automation_task`/`resume_automation_task` execute pipeline in Celery.
+ - AI tasks run async via Celery wrappers (`ai/tasks.py`).
+ 
+ ## Key Design Considerations
+ - Single source of truth for tenancy via base models; prevents cross-tenant data exposure.
+ - Automation mirrors manual flow; manual pages remain usable when automation is paused or disabled.
+ - WordPress publish/sync uses API key auth to avoid storing user credentials beyond site integration config.
+ 
+ ## How Developers Should Work With This Module
+ - When adding new content stages, update both manual endpoints and automation stages.
+ - Ensure every new action that calls AI is wired through `CreditService` and respects site/sector filters.
+ - For new publishing targets, extend `SiteIntegration` and integration service while keeping site/account scoping.

docs/40-WORKFLOWS/PAYMENT-WORKFLOW.md

@@ -0,0 +1,69 @@
+ # Billing Lifecycle
+ 
+ ## Purpose
+ Detail how credits, plans, subscriptions, invoices, and payments flow through the system, and where deductions/additions are enforced.
+ 
+ ## Code Locations (exact paths)
+ - Models: `backend/igny8_core/business/billing/models.py` (`CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `PaymentMethodConfig`, `AccountPaymentMethod`)
+ - Services: `backend/igny8_core/business/billing/services/credit_service.py`, `services/invoice_service.py`, `services/payment_service.py`
+ - Views/Endpoints: `backend/igny8_core/modules/billing/views.py`
+ - Frontend billing pages: `frontend/src/pages/account/{AccountBillingPage.tsx,PlansAndBillingPage.tsx,PurchaseCreditsPage.tsx}`
+ 
+ ## High-Level Responsibilities
+ - Track credit balance, record usage, and enforce costs for AI/automation actions.
+ - Manage plans/subscriptions, generate invoices, and record payments.
+ - Expose account-scoped billing data (balance, usage, invoices, payments, packages, payment methods).
+ 
+ ## Detailed Behavior
+ - Credit balance: stored on `Account.credits`; `CreditService` adds/deducts via `CreditTransaction` and logs usage in `CreditUsageLog`.
+ - Costs: read from `CreditCostConfig` or hardcoded `CREDIT_COSTS` fallbacks inside `credit_service.py`.
+ - Deductions: called from AI/automation flows to ensure sufficient credits; `InsufficientCreditsError` thrown on shortage.
+ - Plans/Subscriptions: `Plan` defines price, billing_cycle, included_credits, max sites/sectors/users; `Subscription` links account to plan. Plan selection handled via billing endpoints and frontend plan tabs.
+ - Invoices: `InvoiceService` creates invoices for subscriptions and credit packages; generates unique invoice numbers and line items.
+ - Payments: `PaymentService` records payments; manual payments stored with status (pending/processing/etc.); payment methods configured via `PaymentMethodConfig`/`AccountPaymentMethod`.
+ - Packages: `CreditPackage` defines purchasable credit bundles; purchasing triggers invoice/payment flows.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Billing: `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `PaymentMethodConfig`, `AccountPaymentMethod`.
+ - Plan: `Plan`, `Subscription` (in `auth/models.py`).
+ - Account linkage: `Account` holds `credits` and `plan`.
+ 
+ ## Execution Flow
+ - Balance/Usage read: billing endpoints return account-scoped balance and usage summaries.
+ - AI/Automation call: service invokes `CreditService.deduct_credits_for_action` → creates `CreditTransaction` + `CreditUsageLog`.
+ - Purchase credits: frontend calls billing endpoint → `CreditService.add_credits` + `InvoiceService` for package; payment recorded via `PaymentService` (manual/other).
+ - Subscription change: endpoint updates `Subscription` + `Account.plan`, generates invoice as needed; payment recorded if required.
+ - Invoice download: `modules/billing/views.py` exposes invoice retrieval; frontend uses `downloadInvoicePDF`.
+ 
+ ## Cross-Module Interactions
+ - Automation/writer AI calls depend on credit checks; insufficient balance blocks operations.
+ - Account settings feed invoice billing details; payments/invoices are tied to account.
+ 
+ ## State Transitions (if applicable)
+ - Payment status: `pending` → `processing/pending_approval` → `succeeded/completed` or `failed/refunded/cancelled/void/uncollectible`.
+ - Subscription status: `active`/`cancelled` (persisted in `Subscription`); plan reference on account updates accordingly.
+ 
+ ## Error Handling
+ - `InsufficientCreditsError` for low balance; surfaces to API as error response.
+ - Payment/Invoice service raise validation errors (e.g., already paid invoice).
+ 
+ ## Tenancy Rules
+ - All billing queries filter by `request.user.account`; viewsets inherit from `AccountModelViewSet`.
+ - Payment methods, invoices, payments, credit transactions are account-scoped; no cross-tenant access.
+ 
+ ## Billing Rules (if applicable)
+ - Costs derived from config constants or `CreditCostConfig`.
+ - Included credits and limits come from `Plan`; extra purchases via `CreditPackage`.
+ - Credits must be available before AI/automation runs proceed.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None dedicated; billing operations are request-driven. Automation tasks carry account context to deduct credits within Celery runs.
+ 
+ ## Key Design Considerations
+ - CreditService centralizes deductions to avoid scattered logic.
+ - Manual payment flow avoids storing sensitive data; relies on transaction_reference and admin approval.
+ 
+ ## How Developers Should Work With This Module
+ - When adding new billable actions, route them through `CreditService` with a defined cost key.
+ - To change pricing, update `CreditCostConfig` data or the `CREDIT_COSTS` fallback map.
+ - Keep all billing endpoints inheriting `AccountModelViewSet` to maintain isolation.

docs/40-WORKFLOWS/SIGNUP-TO-ACTIVE.md

@@ -0,0 +1,77 @@
+ # User Flow Overview
+ 
+ ## Purpose
+ Describe the end-to-end journey from signup through planning, writing, automation, publishing, and billing within IGNY8, mapping each step to concrete backend/frontend modules so engineers can navigate without scanning code.
+ 
+ ## Code Locations (exact paths)
+ - Auth & account: `backend/igny8_core/auth/{views.py,serializers.py,models.py,middleware.py}`, `frontend/src/store/authStore.ts`, routes in `frontend/src/App.tsx`
+ - Planner: `backend/igny8_core/modules/planner/views.py`, `business/planning/models.py`, `frontend/src/pages/Planner/*`
+ - Writer: `backend/igny8_core/modules/writer/views.py`, `business/content/models.py`, `frontend/src/pages/Writer/*`
+ - Automation: `backend/igny8_core/business/automation/{services/automation_service.py,tasks.py,views.py}`, `frontend/src/pages/Automation/AutomationPage.tsx`
+ - Publishing/Integration: `backend/igny8_core/business/integration/{models.py,services/integration_service.py}`, `modules/integration/views.py`, WordPress plugin endpoints consumed via `/api/v1/integration/`; `frontend/src/pages/Sites/*`
+ - Billing: `backend/igny8_core/business/billing/{models.py,services/credit_service.py,services/invoice_service.py,views.py}`, `frontend/src/pages/account/*`
+ - Tenancy enforcement: `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/api/base.py`
+ 
+ ## High-Level Responsibilities
+ - Authenticate users and attach account context to every request.
+ - Let users plan keywords/clusters/ideas, create tasks and content, optionally automate all seven pipeline stages.
+ - Manage sites/sectors and connect WordPress for publishing/sync.
+ - Track credits, plans, subscriptions, invoices, and payments through billing services.
+ 
+ ## Detailed Behavior
+ - Signup/Login: `auth/views.py` issues JWTs; `AccountContextMiddleware` sets `request.account`; frontend `authStore` stores tokens and refreshes them.
+ - Planning: `KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet` create/list/update scoped by `SiteSectorModelViewSet` filters; frontend planner pages drive these endpoints.
+ - Writing: `TasksViewSet`, `ContentViewSet`, `ImagesViewSet` manage tasks/content/images; AI generation endpoints trigger Celery-backed functions.
+ - Automation: `AutomationViewSet` + `automation_service.py` orchestrate 7 stages (keywords→clusters→ideas→tasks→content→image-prompts→images/manual review) with pause/resume and credit estimation; Celery tasks `run_automation_task`/`resume_automation_task` execute runs.
+ - Publishing/Integration: `IntegrationViewSet` handles WP connection tests and sync; WP plugin sends/receives data via API key; content publish endpoints in writer module update WordPress via integration services.
+ - Billing: credit balances and costs computed in `credit_service.py`; invoices via `invoice_service.py`; payments via `payment_service.py`; endpoints in `modules/billing/views.py` feed frontend billing pages.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Tenancy: `Account`, `Site`, `Sector` (plus `SiteUserAccess`), base models `AccountBaseModel`/`SiteSectorBaseModel`.
+ - Planning: `Keywords`, `Clusters`, `ContentIdeas`.
+ - Writing: `Tasks`, `Content`, `Images`.
+ - Automation: `AutomationConfig`, `AutomationRun`.
+ - Billing: `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `Subscription`, `Plan`.
+ - Integration: `SiteIntegration`.
+ 
+ ## Execution Flow
+ 1) User signs in → JWT stored → `AccountContextMiddleware` populates `request.account`.
+ 2) Tenant creates sites/sectors (`SiteViewSet`), selects industry/sectors, optionally connects WordPress.
+ 3) Planner: upload/enter keywords → cluster → generate ideas (manual or via automation/AI functions).
+ 4) Writer: create tasks from ideas, generate content/images (manual endpoints or automation stages).
+ 5) Publish: send to WordPress via integration endpoints or automation publish step; WP plugin syncs back statuses.
+ 6) Automation (optional): run 7-stage pipeline via `AutomationViewSet` + Celery tasks; pause/resume supported.
+ 7) Billing: credits deducted per AI/pipeline usage (`credit_service`), invoices/payments recorded; users view in billing pages.
+ 
+ ## Cross-Module Interactions
+ - Automation invokes planner/writer endpoints/services and logs credit estimates.
+ - Billing hooks into automation and writer AI calls via credit deduction utilities.
+ - Integration uses site/account context and WP API key for sync; writer publish flows depend on integration configuration.
+ 
+ ## State Transitions (if applicable)
+ - Account status (`active/suspended/trial/cancelled`) governs access; plan/subscription affect limits.
+ - Tasks/content/images status transitions handled in writer endpoints; automation run status moves through `created/running/paused/completed/failed`.
+ - Site activation via `set_active`; sectors toggled via `select_sectors`.
+ 
+ ## Error Handling
+ - Unified API responses via `api/response.py`; DRF exception handler configured in settings; frontend shows toasts/banners.
+ - Automation errors logged via `automation_logger`; tasks wrapped in Celery with retries where defined.
+ 
+ ## Tenancy Rules
+ - `AccountContextMiddleware` sets `request.account`; base viewsets filter by account/site/sector; API key auth sets account from `Site.wp_api_key`; public site slug reads limited to active sites.
+ 
+ ## Billing Rules (if applicable)
+ - AI/automation uses `CreditService.deduct_credits_for_action`; credit balance required before runs; plans/subscriptions define included credits and sector/site limits.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery tasks: automation runs (`run_automation_task`, `resume_automation_task`), scheduler `check_scheduled_automations`, AI functions (`ai/tasks.py`), publishing tasks (`tasks/wordpress_publishing.py`).
+ 
+ ## Key Design Considerations
+ - Strong tenant isolation via middleware + filtered querysets.
+ - Automation relies on polling and Celery; frontend automation page polls every 5s during runs.
+ - Billing is authoritative in backend; frontend is read-only except initiating purchases/subscriptions.
+ 
+ ## How Developers Should Work With This Module
+ - Trace user-visible flows by following router → page component → service call → backend viewset.
+ - When adding steps, ensure credit deductions and tenancy filters are applied in the corresponding backend service/viewset.
+ - Keep WP integration changes consistent with API key auth and `SiteIntegration` schema.

docs/50-DEPLOYMENT/DATABASE-MIGRATIONS.md

@@ -0,0 +1,61 @@
+ # Migration Notes
+ 
+ ## Purpose
+ Track significant schema or data migrations, with references to the scripts present in the repo that have been used to adjust data or structure.
+ 
+ ## Code Locations (exact paths)
+ - Migration/utility scripts (repo root `backend/`):
+   - `verify_migrations.py`, `verify_status_fixes.py`, `verify_taxonomy.py`
+   - `fix_*` scripts (e.g., `fix_cluster_status.py`, `fix_content_types.py`, `fix_integration_site_url.py`, `fix_sync.py`, `fix_taxonomy_relationships.py`)
+   - `rename_fields_migration.sql`
+   - `inject_test_data.py`, `sync_idea_status.py`, `check_recent_keywords.py`, `check_api_response.py`, `diagnose_generate_content.py`
+ - Django migrations: `backend/igny8_core/**/migrations/` (per app)
+ 
+ ## High-Level Responsibilities
+ - Capture when ad-hoc fixes or manual SQL were required so future migrations can account for existing state.
+ - Provide guidance on verifying migrations after code changes.
+ 
+ ## Detailed Behavior
+ - Python fix/verify scripts operate against live DBs to patch or validate data (names indicate target domain: clusters/content/integration/taxonomy).
+ - `rename_fields_migration.sql` suggests a manual SQL rename was performed; ensure corresponding Django migration exists or is applied.
+ - `verify_*` scripts check consistency after migrations or data changes.
+ - These scripts are not automatically executed; they are run manually as needed.
+ 
+ ## Execution Flow (Recommended)
+ - Prefer standard Django migrations first: `python manage.py makemigrations && python manage.py migrate`.
+ - For data issues covered by fix scripts:
+   - Review script purpose and run in controlled environment (staging) before production.
+   - Take DB backup before executing manual SQL or fix scripts.
+ - After applying migrations/fixes, run verify scripts to confirm expected state.
+ 
+ ## Cross-Module Interactions
+ - Scripts touch planner/writer/integration data; impacts automation and billing indirectly if content/status changes alter usage.
+ 
+ ## State Transitions (if applicable)
+ - DB schema changes via migrations; data patches via scripts.
+ 
+ ## Error Handling
+ - Scripts log/print outputs; failures will surface during execution; no centralized handler.
+ 
+ ## Tenancy Rules
+ - All scripts should respect account/site scoping; review code before running to ensure filters exist or add them.
+ 
+ ## Billing Rules (if applicable)
+ - None directly; data corrections may affect content/automation counts but not credit logs.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - None; scripts are on-demand.
+ 
+ ## Key Design Considerations
+ - Keep fix/verify scripts version-controlled but treat them as one-off tools; remove or archive obsolete scripts.
+ - Ensure Django migrations are the source of truth for schema; manual SQL should be mirrored in migrations.
+ 
+ ## How Developers Should Work With This Module
+ - Before running any fix/verify script, read it and constrain to target account/site if possible.
+ - Add notes here when new manual interventions occur, including date/purpose and scripts used.
+
+## Recent Hardening (Dec 2025)
+- Throttling bypass for authenticated users to prevent user-facing 429s.
+- AI keys fallback: OpenAI/Runware pulled from system account (`aws-admin`/`default-account`/`default`) or Django settings if tenant key absent.
+- Integration settings restricted to system account or developer (`IsSystemAccountOrDeveloper` backend guard, `AdminGuard` frontend).
+- DRF default permissions tightened to authenticated + tenant access (`IsAuthenticatedAndActive`, `HasTenantAccess`); public endpoints must override explicitly (e.g., AuthViewSet).

docs/50-DEPLOYMENT/DOCKER-DEPLOYMENT.md

@@ -0,0 +1,74 @@
+ # Deployment Guide
+ 
+ ## Purpose
+ Describe how to deploy the IGNY8 stack using the provided Dockerfiles and `docker-compose.app.yml`, including service wiring and required external dependencies.
+ 
+ ## Code Locations (exact paths)
+ - App compose stack: `docker-compose.app.yml`
+ - Backend image: `backend/Dockerfile`
+ - Frontend image: `frontend/Dockerfile`
+ - Backend settings/env: `backend/igny8_core/settings.py`
+ 
+ ## High-Level Responsibilities
+ - Build images for backend, frontend, marketing, and sites renderer.
+ - Bring up the app stack (backend, frontend, marketing, sites, Celery worker, Celery beat) on the shared external network.
+ - Rely on external infra services (Postgres, Redis) defined outside this repo (referenced in compose comments).
+ 
+ ## Detailed Behavior
+ - Backend container:
+   - Image `igny8-backend:latest` from `backend/Dockerfile` (Python 3.11 slim, installs `requirements.txt`, runs Gunicorn on 8010).
+   - Mounted volumes: `/data/app/igny8/backend` (code), `/data/app/igny8` (shared), `/data/app/logs` (logs).
+   - Env vars for DB/Redis and security flags (USE_SECURE_COOKIES/PROXY, DEBUG, SECRET_KEY).
+   - Healthcheck hits `http://localhost:8010/api/v1/system/status/`.
+ - Frontend container:
+   - Image `igny8-frontend-dev:latest` from `frontend/Dockerfile.dev` (built separately; serves via Vite dev server on 5173 exposed as 8021).
+   - Env `VITE_BACKEND_URL`.
+ - Marketing dev and Sites renderer containers: images `igny8-marketing-dev:latest` and `igny8-sites-dev:latest`, ports 8023→5174 and 8024→5176; Sites mounts `/data/app/igny8/sites` and `/data/app/sites-data`.
+ - Celery worker/beat:
+   - Use `igny8-backend:latest`, commands `celery -A igny8_core worker` and `celery -A igny8_core beat`.
+   - Share same DB/Redis env and code volumes.
+ - Network: `igny8_net` marked `external: true`; compose expects Postgres and Redis running in another stack (`/data/app/docker-compose.yml` per comment).
+ - Ports: backend 8011→8010, frontend 8021→5173, marketing 8023→5174, sites 8024→5176.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Not model-specific; relies on runtime env (Postgres DB, Redis broker).
+ 
+ ## Execution Flow
+ - Build images:
+   - `docker build -t igny8-backend:latest -f backend/Dockerfile backend`
+   - `docker build -t igny8-frontend-dev:latest -f frontend/Dockerfile.dev frontend`
+   - `docker build -t igny8-marketing-dev:latest -f frontend/Dockerfile.marketing.dev frontend`
+   - `docker build -t igny8-sites-dev:latest -f sites/Dockerfile.dev sites`
+ - Ensure external infra stack (Postgres, Redis, network `igny8_net`) is up.
+ - Run: `docker compose -f docker-compose.app.yml -p igny8-app up -d`.
+ - Healthcheck will mark backend healthy before frontend depends_on proceeds.
+ 
+ ## Cross-Module Interactions
+ - Backend depends on Postgres/Redis; Celery worker/beat rely on same env to process automation/AI tasks.
+ - Frontend depends on backend health; sites renderer reads deployed sites from `/data/app/sites-data`.
+ 
+ ## State Transitions (if applicable)
+ - Container lifecycle managed by Docker restart policy (`restart: always`).
+ 
+ ## Error Handling
+ - Backend healthcheck fails if status endpoint not reachable; container marked unhealthy causing depends_on wait.
+ - Gunicorn exit surfaces via Docker logs; no auto-restart beyond Docker restart policy.
+ 
+ ## Tenancy Rules
+ - Enforced in application layer via middleware; deployment does not alter tenancy.
+ 
+ ## Billing Rules (if applicable)
+ - None at deployment layer.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery beat runs schedules (e.g., automation scheduler) using same image and env.
+ 
+ ## Key Design Considerations
+ - Compose uses images (not builds) to avoid accidental rebuilds in Portainer; images must exist beforehand.
+ - External network requirement means infra stack must pre-create `igny8_net` and services.
+ - Backend served by Gunicorn with 4 workers per compose command; adjust via compose if scaling container horizontally.
+ 
+ ## How Developers Should Work With This Module
+ - When changing env vars, update `docker-compose.app.yml` and keep parity with `settings.py`.
+ - For new services (e.g., monitoring), add to compose and attach to `igny8_net`.
+ - Keep healthcheck endpoint stable (`/api/v1/system/status/`) or update compose accordingly.

docs/50-DEPLOYMENT/ENVIRONMENT-SETUP.md

@@ -0,0 +1,72 @@
+ # Environment Setup
+ 
+ ## Purpose
+ Outline required runtime dependencies, environment variables, and local setup steps derived from the codebase configuration.
+ 
+ ## Code Locations (exact paths)
+ - Django settings/env: `backend/igny8_core/settings.py`
+ - Backend dependencies: `backend/requirements.txt`
+ - Backend image provisioning: `backend/Dockerfile`
+ - Frontend env/build: `frontend/Dockerfile`, `frontend/package.json`, `frontend/vite.config.ts`
+ - Compose stack env: `docker-compose.app.yml`
+ 
+ ## High-Level Responsibilities
+ - Provide prerequisites for backend (Python 3.11, Postgres, Redis) and frontend (Node 18).
+ - Enumerate environment variables consumed by backend and compose files.
+ - Describe local or containerized setup flows.
+ 
+ ## Detailed Behavior
+ - Backend settings require:
+   - `SECRET_KEY`, `DEBUG`, `USE_SECURE_COOKIES`, `USE_SECURE_PROXY_HEADER`.
+   - Database: `DATABASE_URL` or `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_PORT`; falls back to SQLite in DEBUG if none provided.
+   - Redis/Celery: `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND` default to `redis://{REDIS_HOST}:{REDIS_PORT}/0`.
+   - JWT: `JWT_SECRET_KEY`, expiry defaults (15m access, 30d refresh).
+   - CORS: allowed origins include local ports (5173/5174/5176/8024) and `app.igny8.com`.
+   - Stripe/PayPal keys optional (`STRIPE_PUBLIC_KEY`, `STRIPE_SECRET_KEY`, `PAYPAL_*`).
+ - Backend Dockerfile installs system deps (gcc, libpq-dev) and pip installs `requirements.txt`; runs `collectstatic` (best-effort).
+ - Frontend expects `VITE_BACKEND_URL` (compose sets to `https://api.igny8.com/api`); build via `npm install` then `npm run build` (Dockerfile).
+ - Compose injects DB/Redis env to backend/worker/beat and secure cookie/proxy flags for production use.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Not model-specific; environment affects DB connections, auth, CORS, Celery, billing keys.
+ 
+ ## Execution Flow
+ - Local (backend):
+   - `python -m venv .venv && source .venv/bin/activate`
+   - `pip install -r backend/requirements.txt`
+   - Set env vars (DB/REDIS/JWT/CORS/SECRET_KEY).
+   - `python backend/manage.py migrate` then `python backend/manage.py runserver 8010`.
+ - Local (frontend):
+   - `npm install` in `frontend/`
+   - Set `VITE_BACKEND_URL`
+   - `npm run dev -- --host --port 5173`
+ - Containerized:
+   - Build images per Dockerfiles; run `docker compose -f docker-compose.app.yml up -d` with external Postgres/Redis and network `igny8_net`.
+ 
+ ## Cross-Module Interactions
+ - Celery uses same Redis host/port as defined in env; automation tasks rely on this.
+ - CORS/secure cookie flags must align with frontend host to allow auth.
+ 
+ ## State Transitions (if applicable)
+ - `DEBUG` toggles throttling bypass (`IGNY8_DEBUG_THROTTLE`) and SQLite fallback.
+ 
+ ## Error Handling
+ - Missing DB env → falls back to SQLite in DEBUG; in prod must set Postgres vars.
+ - Healthcheck in compose will fail if env misconfigured and backend cannot start.
+ 
+ ## Tenancy Rules
+ - Unchanged by env; account context enforced in middleware once app runs.
+ 
+ ## Billing Rules (if applicable)
+ - Stripe/PayPal keys optional; without them payment flows are disabled/pending.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Celery broker/backend must be reachable; worker/beat require the same env set.
+ 
+ ## Key Design Considerations
+ - Prefer Postgres in all shared/test/prod; SQLite only for local development.
+ - Keep SECRET_KEY/JWT keys distinct and secret in production.
+ 
+ ## How Developers Should Work With This Module
+ - Add new env variables in `settings.py` with safe defaults; document in this file.
+ - Mirror envs in compose and deployment systems (Portainer/CI) to avoid drift.

docs/90-ARCHIVED/README.md

@@ -0,0 +1,38 @@
+# Archived Documentation
+
+**Purpose:** Historical reference from previous documentation systems
+
+## Contents
+
+### master-docs-original/
+Original master documentation structure (pre-December 2024 consolidation)
+- Comprehensive but scattered across many files
+- Retained for historical reference
+- **Do not use for active development**
+
+### old-docs-original/
+Legacy documentation from earlier iterations
+- Contains older API references
+- Has some WordPress-specific guides
+- **Do not use for active development**
+
+## Current Documentation
+
+All active documentation has been consolidated into:
+- `/docs/` - Single source of truth
+- See `/docs/README.md` for navigation
+
+## When to Reference Archived Docs
+
+✅ Historical context for old decisions  
+✅ Finding deprecated features  
+✅ Understanding system evolution  
+
+❌ NOT for current development  
+❌ NOT for API references  
+❌ NOT for implementation guides  
+
+---
+
+**Last Archived:** December 9, 2024  
+**Reason:** Documentation consolidation project

docs/90-ARCHIVED/master-docs-original/00-system/00-SYSTEM-ARCHITECTURE-OVERVIEW.md

@@ -0,0 +1,79 @@
+# System Architecture Overview
+
+## Purpose
+Describe how IGNY8 is structured across backend, frontend, and integrations, grounded in the current codebase. Covers core services, middleware, and platform composition.
+
+## Code Locations (exact paths)
+- Backend project root: `backend/igny8_core/`
+- Settings and service wiring: `backend/igny8_core/settings.py`
+- URL routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/middleware/resource_tracker.py`, `backend/igny8_core/auth/middleware.py`
+- Auth models and tenancy bases: `backend/igny8_core/auth/models.py`
+- DRF base behaviors: `backend/igny8_core/api/base.py`
+- Custom auth classes: `backend/igny8_core/api/authentication.py`
+- Frontend SPA: `frontend/` (Vite + React; dependencies in `frontend/package.json`)
+
+## High-Level Responsibilities
+- Django/DRF backend providing multi-tenant APIs for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
+- Middleware adds per-request IDs, tenant context, and optional resource tracking for admin diagnostics.
+- REST API routing under `/api/v1/*` with unified response/error handling and scoped throttling.
+- Celery-backed async work (configured in settings) for AI, automation, and publishing.
+- React/Vite frontend consuming the API; authentication via JWT or session; API key support for WordPress bridge.
+
+## Detailed Behavior
+- Backend apps registered in `INSTALLED_APPS` include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, and publisher modules; these are loaded via Django app configs in `settings.py`.
+- Middleware order enforces security, CORS, session, CSRF, Django auth, then custom layers: request ID, account context, resource tracking, messages, and clickjacking protection.
+- URL map (`urls.py`) exposes admin, CSV admin utilities for industries/seed keywords, and module routers for auth, account, planner, writer, system, billing (user + admin), automation, linker, optimizer, publisher, and integration. OpenAPI docs available at `/api/docs` and `/api/redoc`.
+- REST framework defaults use custom pagination, filtering, search, ordering, and a custom exception handler (enabled unless `IGNY8_USE_UNIFIED_EXCEPTION_HANDLER` is false). Authentication stack orders API key, JWT, CSRF-exempt session, then basic auth. Throttle scopes are predefined per domain (AI, content, auth, planner, writer, system, billing, linker, optimizer, integration).
+- CORS allows the IGNY8 domains plus local development hosts; credentials and specific debug headers are permitted, and request/resource tracking IDs are exposed in response headers.
+- Celery is configured to use Redis by default for broker and result backend, with JSON serialization, task time limits, and single-prefetch workers.
+- Logging writes to console and rotating files for publish/sync, WordPress API calls, and webhooks, with request IDs available via middleware.
+
+## Data Structures / Models Involved (no code, just explanation)
+- Multi-tenancy base classes (`AccountBaseModel`, `SiteSectorBaseModel`) add `account`, `site`, and `sector` scoping plus validation; defined in `auth/models.py`.
+- Core tenancy entities: `Account`, `Plan`, `Subscription`, `Site`, `Sector`, `Industry`, `IndustrySector`, `SeedKeyword`, `SiteUserAccess`, `User`, and `PasswordResetToken` in `auth/models.py`.
+- These bases are consumed by downstream modules (planner, writer, billing, automation, etc.) to enforce tenant, site, and sector ownership.
+
+## Execution Flow
+- Incoming HTTP requests enter Django middleware: security → WhiteNoise → CORS → session → common/CSRF → Django auth → `RequestIDMiddleware` (assigns `X-Request-ID`) → `AccountContextMiddleware` (sets `request.account` via session or JWT) → `ResourceTrackingMiddleware` (when enabled for admins) → messages → clickjacking.
+- DRF viewsets inherit from base classes in `api/base.py` to auto-filter querysets by account (and site/sector where applicable) and emit unified responses.
+- URL dispatch routes to module-specific routers under `/api/v1/*`. CSV admin helpers are mounted before admin to avoid routing conflicts.
+- Background tasks are dispatched via Celery using Redis endpoints from `settings.py`.
+
+## Cross-Module Interactions
+- Auth middleware sets `request.account` consumed by `AccountModelViewSet` and `SiteSectorModelViewSet` to filter data.
+- API key auth (WordPress bridge) sets both `request.account` and `request.site` for integration endpoints.
+- Resource tracking middleware exposes metrics via cache keyed by the request-specific tracking ID added to responses.
+- OpenAPI generation (drf-spectacular) documents all modules and respects unified response schemas.
+
+## State Transitions (if applicable)
+- Request lifecycle: ID assignment → tenant resolution → optional resource profiling → viewset execution → unified response with optional pagination and request/resource IDs in headers.
+- Tenancy lifecycle: Account/Plan/Subscription fields in models track status and retention; soft delete support on models that implement it.
+
+## Error Handling
+- Global DRF exception handler (custom when enabled) wraps errors into unified JSON with `success=false`.
+- Account middleware denies access when account or plan is missing/inactive, returning structured JSON and logging out session users.
+- Viewset overrides in `api/base.py` return unified error payloads for validation and 404/500 cases.
+
+## Tenancy Rules
+- Account is injected via middleware (session or JWT). Base viewsets filter querysets by `account`, unless the user is admin/developer/system account (override path).
+- `SiteSectorModelViewSet` adds site/sector filtering when models carry those fields; validation ensures site/sector belong to the same account.
+- Role helpers (`User.is_admin_or_developer`, `User.is_system_account_user`) allow bypass for privileged users; otherwise, data is restricted to the resolved account (and site/sector for derived models).
+
+## Billing Rules (if applicable)
+- Plan and account billing fields live in `auth/models.py` (`Plan.included_credits`, `Account.credits`, Stripe IDs). Status enforcement occurs in `AccountContextMiddleware` by requiring an active plan; billing modules implement credit logic (covered in backend/billing docs).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery configuration in `settings.py` sets Redis broker/backend, JSON serialization, time limits, and worker tuning. Task modules (AI, automation, publishing) use this setup; scheduling uses Celery Beat state.
+
+## Key Design Considerations
+- Middleware-first tenant resolution ensures consistent scoping before view logic.
+- Admin/developer/system-account overrides allow cross-tenant operations for ops while protecting system accounts from deletion.
+- Unified API responses and throttling scopes enforce consistent client behavior and rate safety.
+- Redis-backed Celery keeps async workloads out of request path with strict time limits.
+
+## How Developers Should Work With This Module
+- Add new apps to `INSTALLED_APPS` and mount URLs under `/api/v1/*` in `urls.py`.
+- Inherit from `AccountModelViewSet` or `SiteSectorModelViewSet` to automatically enforce tenant/site/sector scoping and unified responses.
+- Use existing middleware; do not reorder request ID or account context layers, as downstream views rely on them.
+- Configure environment via `settings.py` variables (DB, JWT, Celery, CORS, Stripe/PayPal) rather than hardcoding values.

docs/90-ARCHIVED/master-docs-original/00-system/01-TECH-STACK.md

@@ -0,0 +1,61 @@
+# Tech Stack
+
+## Purpose
+Document the concrete technologies and dependencies in use across backend and frontend as defined in the repository.
+
+## Code Locations (exact paths)
+- Backend dependency manifest: `backend/requirements.txt`
+- Backend settings (framework integration): `backend/igny8_core/settings.py`
+- Frontend dependency manifest: `frontend/package.json`
+- Frontend build tooling: `frontend/vite.config.ts`, `frontend/tsconfig*.json`
+
+## High-Level Responsibilities
+- Backend: Django 5.x with DRF for APIs, Celery for async tasks, Redis for broker/result, PostgreSQL or SQLite for data, drf-spectacular for OpenAPI, Stripe/PayPal configs for billing, WhiteNoise for static serving.
+- Frontend: React 19 with Vite, TypeScript, TailwindCSS, Zustand state, React Router 7, ApexCharts and FullCalendar for UI widgets.
+
+## Detailed Behavior
+- Backend settings wire DRF pagination, filters, authentication (API key, JWT, session, basic), throttling, schema generation, CORS, Celery, logging, and Stripe/PayPal credentials. Static assets are served via WhiteNoise; admin uses Django contrib.
+- `requirements.txt` enumerates runtime libs: Django, gunicorn, psycopg2-binary (PostgreSQL), redis, WhiteNoise, DRF, django-filter, django-cors-headers, PyJWT, requests, Celery, BeautifulSoup4, psutil, docker (for ops scripts), drf-spectacular, and stripe.
+- Frontend `package.json` pins React 19, React Router 7, Zustand 5, Vite 6, TailwindCSS 4, ApexCharts 4, FullCalendar 6, react-dnd, dropzone, lucide/react-heroicons, and testing/tooling (Vitest, Testing Library, ESLint).
+- Build scripts use Vite for dev and production builds, with separate marketing mode; tests via Vitest; lint via ESLint; type-check via `tsc -b`.
+
+## Data Structures / Models Involved (no code)
+- Not applicable; this file tracks technology components rather than domain models.
+
+## Execution Flow
+- Backend runs under Django/DRF with middleware and installed apps per `settings.py`. ASGI/WSGI entrypoints in `igny8_core/asgi.py` and `igny8_core/wsgi.py` (default WSGI via gunicorn).
+- Celery worker/beat use Redis URLs from `settings.py` and respect JSON serialization/time limits.
+- Frontend builds with Vite, consuming environment variables defined via Vite conventions.
+
+## Cross-Module Interactions
+- DRF auth classes depend on PyJWT and custom utilities for token handling.
+- Celery tasks in AI/automation/publishing rely on Redis connectivity and the configured serializer/time limits.
+- Stripe/PayPal keys in settings are consumed by billing modules.
+- Frontend API calls rely on the DRF endpoints exposed in `igny8_core/urls.py`.
+
+## State Transitions (if applicable)
+- Dependency-driven: none beyond the build/runtime phases (install → build → serve).
+
+## Error Handling
+- Backend error handling configured via custom DRF exception handler (enabled by default) and logging setup in `settings.py`.
+- Frontend build/test errors are surfaced through Vite/TypeScript/Vitest/ESLint tooling.
+
+## Tenancy Rules
+- Implemented at runtime by backend middleware and viewsets; the tech stack provides JWT, session, and API key support to carry tenant context.
+
+## Billing Rules (if applicable)
+- Stripe and PayPal keys in `settings.py` enable billing integrations; credit logic is implemented in billing modules (documented elsewhere).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery configured in `settings.py` with Redis broker/backend, JSON serialization, and task limits; beat scheduling persists in `celerybeat-schedule`.
+
+## Key Design Considerations
+- Keep dependency manifests authoritative (`requirements.txt`, `package.json`).
+- Redis is the default async backbone; Postgres is the default DB with SQLite fallback for local/dev.
+- Vite + React 19 selected for fast dev/build; TailwindCSS 4 used for styling; Zustand for state.
+
+## How Developers Should Work With This Module
+- Add backend dependencies to `requirements.txt` and pin versions appropriately; update settings if new middleware/auth is added.
+- Add frontend dependencies to `package.json`; run `npm install` and ensure Vite/TSC builds remain clean.
+- Respect configured auth stack (API key → JWT → session) when adding API clients.
+- Keep CORS and env vars aligned with the domains/ports in use for local and production.

docs/90-ARCHIVED/master-docs-original/00-system/02-MULTITENANCY-MODEL.md

@@ -0,0 +1,79 @@
+# Multitenancy Model
+
+## Purpose
+Explain how tenant, site, and sector isolation is enforced across models, middleware, and viewsets, based on the current implementation.
+
+## Code Locations (exact paths)
+- Tenant base models: `backend/igny8_core/auth/models.py` (`AccountBaseModel`, `SiteSectorBaseModel`)
+- Core entities: `backend/igny8_core/auth/models.py` (`Account`, `Plan`, `Site`, `Sector`, `Industry`, `IndustrySector`, `SeedKeyword`, `SiteUserAccess`, `User`)
+- Middleware for context: `backend/igny8_core/auth/middleware.py`
+- DRF base viewsets: `backend/igny8_core/api/base.py`
+- Auth utilities and JWT: `backend/igny8_core/api/authentication.py`, `backend/igny8_core/auth/utils.py`
+- URL routing (module mounting): `backend/igny8_core/urls.py`
+
+## High-Level Responsibilities
+- Enforce per-account isolation for all models carrying an `account` FK.
+- Enforce per-site and per-sector scoping for content models via `SiteSectorBaseModel`.
+- Inject tenant context on every request (session or JWT/API key), then apply scoping in base viewsets.
+- Allow controlled overrides for admins, developers, and system accounts.
+
+## Detailed Behavior
+- `AccountBaseModel` adds an `account` FK plus timestamps and indexes; all tenant-scoped models inherit this to guarantee account linkage.
+- `SiteSectorBaseModel` extends `AccountBaseModel` with `site` and `sector` FKs, indexes on `(account, site, sector)`, and a save hook that sets `account` from `site` and validates that `sector` belongs to the same `site`; raises validation errors on mismatch.
+- `AccountContextMiddleware` sets `request.account` by refreshing the authenticated session user (with account and plan) or by decoding JWT tokens; it rejects requests when account is missing or plan is inactive, returning structured JSON and logging out session users. It skips admin and auth endpoints to avoid interference.
+- JWT authentication (`api/authentication.py`) decodes tokens and sets `request.account` from the token payload; API key authentication sets both `request.account` and `request.site` for WordPress bridge calls.
+- `AccountModelViewSet` auto-filters querysets by `account` when models expose that field. It bypasses filtering for admins/developers/system-account users; otherwise, it uses `request.account` or falls back to the authenticated user’s account. Creates set `account` on save when present.
+- `SiteSectorModelViewSet` extends the above to filter by site/sector if those fields exist, using request query parameters and tenancy context.
+- `User` role helpers (`is_admin_or_developer`, `is_system_account_user`) and account checks gate override behavior.
+- `SiteUserAccess` provides explicit per-site access for non-admin roles; `User.get_accessible_sites` respects system account, developer, owner/admin, and granted access rules.
+
+## Data Structures / Models Involved (no code)
+- `Account`: tenant container with plan, credits, billing fields, status, and retention settings.
+- `Plan`: defines limits (max users/sites/industries/author profiles), credit inclusion, Stripe IDs.
+- `Site`: belongs to an account, optionally an industry; includes status, hosting type, legacy WP fields, and SEO metadata.
+- `Sector`: belongs to a site and industry sector template; enforces account alignment and plan-based max-sector validation.
+- `Industry`, `IndustrySector`, `SeedKeyword`: global reference data not bound to a single account.
+- `SiteUserAccess`: explicit many-to-many grants between users and sites.
+- `User`: links to account with role-based access flags.
+
+## Execution Flow
+- Request enters middleware; `AccountContextMiddleware` determines `request.account` (session or JWT/API key), validating plan status.
+- Viewsets inheriting from `AccountModelViewSet`/`SiteSectorModelViewSet` filter querysets by `account` (and site/sector when present) before pagination/serialization.
+- Object creation sets `account` automatically when the serializer’s model has that field; site/sector-based models validate alignment on save.
+- Admin/developer/system-account users skip account filtering; other users remain constrained.
+
+## Cross-Module Interactions
+- All module viewsets depend on the base viewsets for scoping.
+- Automation, planner, writer, billing, linker, optimizer, publisher, and integration models inherit from the tenancy bases to enforce account/site/sector ownership.
+- API key flows for WordPress set `request.site`, enabling integration-specific logic to run in a site-aware context.
+
+## State Transitions (if applicable)
+- Account status changes (active, suspended, trial, cancelled) and plan activation directly affect access through middleware plan validation.
+- Sector creation enforces plan-based limits for active sectors per site.
+
+## Error Handling
+- Middleware returns JSON errors for missing account or inactive plan, with HTTP 403 or 402 semantics and logs out session users.
+- Base viewsets wrap CRUD operations in unified responses; validation failures or missing objects are returned in structured error payloads.
+- Save-time validation on `SiteSectorBaseModel` and `Sector` raises validation errors when site/sector alignment or plan limits are violated.
+
+## Tenancy Rules
+- Every tenant-scoped model carries `account`; site/sector-aware models carry `site` and `sector` and must align to the same account.
+- Middleware populates `request.account`; base viewsets enforce filtering unless the user is an admin/developer/system-account member.
+- System accounts (`aws-admin`, `default-account`, `default`) and privileged roles can bypass scoping; protected from deletion via guard clauses.
+
+## Billing Rules (if applicable)
+- Middleware requires an active plan before allowing requests (except auth/admin paths). Credits, charges, and plan enforcement are handled in billing modules (documented elsewhere).
+
+## Background Tasks / Schedulers (if applicable)
+- Celery tasks inherit tenant context via payloads supplied by calling viewsets/services; the tenancy bases ensure stored records retain `account`/`site`/`sector`.
+
+## Key Design Considerations
+- Tenancy is enforced as early as middleware to avoid leakage in view logic.
+- Base viewsets centralize scoping and unified responses to reduce duplication across modules.
+- Role-based overrides exist for ops and system accounts; safeguards prevent system account deletion.
+
+## How Developers Should Work With This Module
+- Inherit from `AccountBaseModel` or `SiteSectorBaseModel` for any new tenant/site/sector data models.
+- Inherit viewsets from `AccountModelViewSet` or `SiteSectorModelViewSet` to get automatic scoping and unified responses.
+- Do not bypass `AccountContextMiddleware`; ensure new endpoints live under `/api/v1/*` and rely on the auth stack (API key → JWT → session).
+- Validate that new background tasks carry account/site/sector identifiers so downstream saves remain scoped.

docs/90-ARCHIVED/master-docs-original/00-system/03-IDENTITY-AND-AUTHENTICATION.md

@@ -0,0 +1,73 @@
+# Identity and Authentication
+
+## Purpose
+Document how user identity, JWT handling, API keys, and session flows work, including middleware and validation rules.
+
+## Code Locations (exact paths)
+- JWT utilities: `backend/igny8_core/auth/utils.py`
+- Account context middleware: `backend/igny8_core/auth/middleware.py`
+- DRF authentication classes: `backend/igny8_core/api/authentication.py`
+- DRF settings for auth/throttle: `backend/igny8_core/settings.py`
+- User model and roles: `backend/igny8_core/auth/models.py`
+- Auth URLs and views: `backend/igny8_core/auth/urls.py`, `backend/igny8_core/auth/views.py`
+
+## High-Level Responsibilities
+- Support multiple auth mechanisms: API key (WordPress bridge), JWT bearer tokens, session auth without CSRF for APIs, and basic auth fallback.
+- Populate tenant/site context alongside user identity so downstream viewsets enforce isolation.
+- Enforce active account/plan presence before serving protected endpoints (except admin/auth routes).
+
+## Detailed Behavior
+- Authentication order (DRF `DEFAULT_AUTHENTICATION_CLASSES` in `settings.py`): API key → JWT → CSRF-exempt session → basic auth. The first class that authenticates sets `request.user`; `request.account` may also be set by API key or JWT.
+- API Key flow (`APIKeyAuthentication`): expects `Authorization: Bearer <api_key>` that is not JWT-like; finds an active `Site` with `wp_api_key`, loads its `account`, and selects an active user (owner preferred, else any active developer/owner/admin). Sets `request.account` and `request.site`. Rejects short/invalid keys; returns an auth failure if no active user exists.
+- JWT flow (`JWTAuthentication`): expects `Authorization: Bearer <jwt>`; decodes via `auth.utils.decode_token`; only accepts tokens with `type == access`. Retrieves `User` by `user_id`; optional `account_id` is resolved to `Account` and set on `request.account`. Invalid/expired tokens fall through to other auth classes.
+- Session flow (`CSRFExemptSessionAuthentication`): uses Django session cookies without CSRF enforcement for API calls.
+- Basic auth: last resort; does not set tenant context.
+- Token utilities (`auth/utils.py`) generate and decode access/refresh tokens using expiries from settings (`JWT_ACCESS_TOKEN_EXPIRY`, `JWT_REFRESH_TOKEN_EXPIRY`), embedding `user_id`, `account_id`, `email`, issued/expiry timestamps, and token `type`.
+- Middleware (`AccountContextMiddleware`) runs on every request except admin/auth paths: refreshes session users from DB to pick up current account/plan, validates presence of an active plan, sets `request.account`, and logs out session users when invalid. For JWT-bearing requests it decodes the token directly and sets `request.account`. If account/plan is missing or inactive, it returns JSON with `success=false` and appropriate HTTP status.
+
+## Data Structures / Models Involved (no code)
+- `User` with `role` and `account` FKs in `auth/models.py`.
+- `Account` with plan and billing fields; plan status is used for access gating.
+- `Site` with `wp_api_key` for API key auth; `SiteUserAccess` for per-site grants.
+- `PasswordResetToken` model for password reset flows.
+- JWT payload fields: `user_id`, `account_id`, `email`, `exp`, `iat`, `type`.
+
+## Execution Flow
+- Middleware step: `AccountContextMiddleware` determines `request.account` (session or JWT) and validates plan status; skips admin/auth routes.
+- DRF auth step: API key/JWT/session/basic authenticators run in order, potentially setting `request.account` (API key/JWT) and `request.site` (API key).
+- Viewsets then apply role/permission checks and tenant/site/sector filtering via base classes in `api/base.py`.
+
+## Cross-Module Interactions
+- All module viewsets rely on `request.user` and `request.account` set by the auth stack. Site-aware modules can read `request.site` when API key auth is used.
+- Role helpers (`is_admin_or_developer`, `is_system_account_user`) influence filtering bypass in base viewsets.
+
+## State Transitions (if applicable)
+- JWT lifetimes: access tokens default to 15 minutes; refresh tokens to 30 days (configurable in settings).
+- Session users are refreshed on each request to pick up plan/account changes.
+- Password reset tokens track expiry and usage via `expires_at` and `used` flags.
+
+## Error Handling
+- Middleware returns JSON errors for missing account or inactive plan and logs out session users in those cases.
+- Invalid/expired JWTs cause the JWT authenticator to return `None`, allowing other auth methods; decoding errors raise `InvalidTokenError` in utilities.
+- API key auth raises an auth failure when no active user is available for the resolved account.
+
+## Tenancy Rules
+- `request.account` is set early; base viewsets enforce account filtering unless user has admin/developer/system-account privileges.
+- API key auth also sets `request.site` for integration contexts; site/sector filtering occurs in `SiteSectorModelViewSet`.
+
+## Billing Rules (if applicable)
+- Active plan is required for access (middleware enforces). Credit debits/charges are handled in billing modules, not in the auth layer.
+
+## Background Tasks / Schedulers (if applicable)
+- Token generation/validation is synchronous. Background tasks should receive explicit user/account identifiers in their payloads when invoked.
+
+## Key Design Considerations
+- Authentication stack is ordered to give integration API keys precedence, then JWT for app clients, then session for browser-based flows.
+- Tenant context must be established before view logic; do not move or remove `AccountContextMiddleware`.
+- Expiry durations and JWT secrets are centrally configured in `settings.py`.
+
+## How Developers Should Work With This Module
+- Use token helpers from `auth/utils.py` when issuing tokens; do not handcraft JWTs.
+- Mount new auth-sensitive endpoints under existing routers and rely on DRF auth classes instead of custom header parsing.
+- Ensure new features that require site context can work with API key auth by checking `request.site`.
+- Keep plan enforcement in place; bypass only for admin/system routes when justified.

docs/90-ARCHIVED/master-docs-original/00-system/04-DATA-FLOW-DIAGRAMS.md

@@ -0,0 +1,85 @@
+# Data Flow Diagrams (Narrative)
+
+## Purpose
+Describe end-to-end data movement through the system based on current routing, middleware, and model conventions. No diagrams are embedded; flows are explained textually.
+
+## Code Locations (exact paths)
+- Request routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/middleware/resource_tracker.py`
+- DRF base viewsets: `backend/igny8_core/api/base.py`
+- Authentication classes: `backend/igny8_core/api/authentication.py`
+- Tenancy models: `backend/igny8_core/auth/models.py`
+- Celery configuration: `backend/igny8_core/settings.py`
+
+## High-Level Responsibilities
+- Trace how HTTP requests are processed, tenant-scoped, authorized, and persisted.
+- Show where async processing departs to Celery and where responses are shaped.
+
+## Detailed Behavior
+- Incoming request → Django middleware stack:
+  - Security/WhiteNoise/CORS/session/common/CSRF/Django auth.
+  - `RequestIDMiddleware` assigns `request.request_id` and returns it in `X-Request-ID`.
+  - `AccountContextMiddleware` resolves user/account (session or JWT) and enforces active plan; sets `request.account`.
+  - `ResourceTrackingMiddleware` optionally tracks resource usage for admin/developer users when the `X-Debug-Resource-Tracking` header is true; adds `X-Resource-Tracking-ID`.
+- URL dispatch via `urls.py` routes to module routers (auth, account, planner, writer, system, billing, automation, linker, optimizer, publisher, integration) under `/api/v1/*`.
+- DRF viewset pipeline:
+  - Authentication classes (API key → JWT → session → basic) establish `request.user` (and optionally `request.account`/`request.site`).
+  - Base viewsets (`AccountModelViewSet`, `SiteSectorModelViewSet`) filter querysets by `account`/`site`/`sector` and attach `account` on create.
+  - Serializers handle validation; responses are wrapped by unified helpers to standardize success/error payloads and pagination.
+- Persistence:
+  - Tenant-scoped models inherit `AccountBaseModel` or `SiteSectorBaseModel`; save hooks enforce account/site/sector alignment.
+  - Soft deletion is used where models implement `soft_delete`, respecting retention windows from account settings.
+- Async/Background:
+  - Celery uses Redis broker/backend; tasks inherit JSON payloads and time limits from `settings.py`.
+  - Automation, AI, publishing, and billing tasks enqueue via Celery; results return through database/state updates, not synchronous responses.
+- Response:
+  - Unified response wrappers ensure `success`, `data`/`error`, and request ID are present; paginated responses include `count/next/previous/results`.
+  - Throttling headers apply per-scope (as configured in `REST_FRAMEWORK` throttles).
+
+## Data Structures / Models Involved (no code)
+- Tenancy bases: `AccountBaseModel`, `SiteSectorBaseModel`.
+- Core entities: `Account`, `Plan`, `Site`, `Sector`, `User`, `SiteUserAccess`.
+- Module-specific models follow the same tenancy bases (documented in module-specific files).
+
+## Execution Flow
+1) HTTP request hits middleware; IDs and tenant context are set.  
+2) DRF authentication authenticates and sets user/account/site.  
+3) Viewset filters data by tenant/site/sector and runs serializer validation.  
+4) DB operations persist data with enforced tenant alignment.  
+5) Optional Celery tasks are queued for long-running work.  
+6) Response returns unified JSON with request IDs and optional throttling/pagination headers.
+
+## Cross-Module Interactions
+- Auth context set in middleware is consumed by all module viewsets for scoping.
+- API key auth provides site context for integration/publisher flows.
+- Celery configuration is shared by automation/AI/publishing/billing task modules.
+
+## State Transitions (if applicable)
+- Entity lifecycle changes (create/update/delete/soft-delete) flow through base viewsets and tenancy bases, ensuring account/site/sector consistency.
+- Request lifecycle includes request ID creation, optional resource tracking, and unified response wrapping.
+
+## Error Handling
+- Middleware can short-circuit with JSON errors for missing account/plan.
+- Viewset overrides wrap validation and server errors into unified responses; missing objects return 404 payloads.
+- Throttling (scope-based) returns standard DRF throttle responses with headers.
+
+## Tenancy Rules
+- All tenant-bound data flows require `request.account`; filtering and save hooks prevent cross-tenant access.
+- Admin/developer/system-account users may bypass tenant filtering; system accounts are guarded against deletion.
+- Site/sector alignment is validated on save for models inheriting `SiteSectorBaseModel`.
+
+## Billing Rules (if applicable)
+- Plan activation is validated in middleware. Credit debits and billing workflows occur in billing modules (covered elsewhere) after tenant resolution.
+
+## Background Tasks / Schedulers (if applicable)
+- Celery broker/backend configuration in `settings.py` governs async flow; tasks should include account/site identifiers to maintain scoping.
+
+## Key Design Considerations
+- Request ID and resource tracking enable traceability and performance debugging.
+- Middleware ordering ensures tenant context precedes view logic.
+- Unified response format keeps clients consistent across modules.
+
+## How Developers Should Work With This Module
+- Preserve middleware order; new middleware must not break request ID or tenant context.
+- Ensure new viewsets inherit the base classes to pick up scoping and unified responses.
+- When adding async tasks, include tenant/site identifiers and respect Celery limits from settings.

docs/90-ARCHIVED/master-docs-original/00-system/05-PERMISSIONS-AND-ACCESS-CONTROL.md

@@ -0,0 +1,74 @@
+# Permissions and Access Control
+
+## Purpose
+Explain role-based permissions, account ownership rules, and how viewsets enforce access across the stack.
+
+## Code Locations (exact paths)
+- Role-based permissions: `backend/igny8_core/auth/permissions.py`
+- User roles and helpers: `backend/igny8_core/auth/models.py`
+- Account context middleware: `backend/igny8_core/auth/middleware.py`
+- Base viewsets with override/bypass logic: `backend/igny8_core/api/base.py`
+- DRF settings: `backend/igny8_core/settings.py`
+
+## High-Level Responsibilities
+- Enforce role-based access (developer, owner, admin, editor, viewer, system_bot).
+- Enforce tenant/site/sector scoping with selective overrides for privileged roles.
+- Block access when accounts lack active plans.
+
+## Detailed Behavior
+- Roles are stored on `User.role`; helper methods (`is_admin_or_developer`, `is_developer`, `is_system_account_user`, `has_role`) drive bypass logic.
+- Permission classes:
+  - `IsOwnerOrAdmin`: allows authenticated users with roles owner/admin/developer or superuser.
+  - `IsEditorOrAbove`: allows editor/admin/owner/developer or superuser.
+  - `IsViewerOrAbove`: allows any authenticated user.
+  - `AccountPermission`: ensures the user is authenticated, not a system bot unless intended, and matches object account when present; system bots bypass account checks.
+- Base viewsets:
+  - `AccountModelViewSet` filters by `account` unless `is_admin_or_developer` or `is_system_account_user` is true; create sets `account` automatically; delete protects system account slugs.
+  - `SiteSectorModelViewSet` extends filtering to `site`/`sector` when models have those fields.
+- Middleware:
+  - `AccountContextMiddleware` denies requests when user lacks an account or active plan (403/402), logging out session users and returning JSON errors.
+- System accounts (`aws-admin`, `default-account`, `default`) and system bots are privileged; system accounts are protected from deletion.
+
+## Data Structures / Models Involved (no code)
+- `User` with `role` and account FK.
+- `Account` with `status` and `plan` used for gating.
+- `SiteUserAccess` for per-site grants evaluated by `User.get_accessible_sites`.
+
+## Execution Flow
+- Middleware validates account/plan and sets `request.account`.
+- DRF authentication sets `request.user`; permission classes on views (and base viewsets) check role/account match.
+- Querysets are filtered by tenant/site/sector; privileged roles may bypass filtering.
+- Soft-delete or delete operations respect system account protection.
+
+## Cross-Module Interactions
+- All module viewsets inherit base classes, so account/site/sector scoping and role-based bypass apply uniformly.
+- Integration endpoints using API key auth rely on `request.site`/`request.account` set earlier.
+
+## State Transitions (if applicable)
+- Account status and plan activation affect access; changing these alters middleware decisions immediately due to per-request user refresh.
+
+## Error Handling
+- Middleware returns structured JSON errors for missing account or inactive plan.
+- Base viewsets wrap permission and validation failures into unified error responses.
+- Permission classes return standard DRF permission denials for unauthenticated/unauthorized users.
+
+## Tenancy Rules
+- Default: filter data to `request.account`; site/sector models further constrain by site/sector.
+- Overrides: developers/admins/system-account users can see across accounts; system bots can access any account/object; system accounts cannot be deleted.
+
+## Billing Rules (if applicable)
+- Active plan required; enforced in middleware before permission checks.
+
+## Background Tasks / Schedulers (if applicable)
+- Background tasks should be invoked with account/site identifiers to maintain the same isolation rules; role checks occur at request time, not within tasks.
+
+## Key Design Considerations
+- Centralize role checks to avoid per-view duplication.
+- Maintain middleware-first gating to prevent expensive processing before authorization.
+- Preserve protection of system accounts and allow ops-level overrides without compromising tenant isolation.
+
+## How Developers Should Work With This Module
+- Apply permission classes (`IsOwnerOrAdmin`, `IsEditorOrAbove`, etc.) on viewsets/endpoints as needed.
+- Always inherit from `AccountModelViewSet`/`SiteSectorModelViewSet` for scoped data access.
+- Avoid bypassing middleware plan checks; if admin-only, use explicit admin routes instead.
+- When adding new privileged behaviors, reuse `User` role helpers and system-account detection.

docs/90-ARCHIVED/master-docs-original/00-system/06-ENVIRONMENT-VARIABLES.md

@@ -0,0 +1,91 @@
+# Environment Variables
+
+## Purpose
+List environment variables that influence runtime behavior, taken directly from `settings.py` and related auth/Celery configuration.
+
+## Code Locations (exact paths)
+- Primary definitions and defaults: `backend/igny8_core/settings.py`
+- JWT helpers: `backend/igny8_core/auth/utils.py`
+
+## High-Level Responsibilities
+- Configure secrets, debug flags, DB connections, CORS, auth, Celery, and billing providers without code changes.
+
+## Detailed Behavior
+- Core flags:
+  - `SECRET_KEY` (required for production)
+  - `DEBUG` (enables debug when set to true)
+  - `IGNY8_DEBUG_THROTTLE` (bypass rate limiting when true; defaults to `DEBUG`)
+  - `IGNY8_USE_UNIFIED_EXCEPTION_HANDLER` (controls custom DRF exception handler; enabled by default)
+  - `USE_SITE_BUILDER_REFACTOR` (feature flag for site builder)
+  - `USE_SECURE_COOKIES` (sets session/CSRF secure cookies)
+  - `USE_SECURE_PROXY_HEADER` (enables `SECURE_PROXY_SSL_HEADER`)
+  - `USE_X_FORWARDED_HOST` is disabled by default; no env provided.
+- Database selection (PostgreSQL default with SQLite fallbacks):
+  - `DATABASE_URL` (parsed for engine/user/pass/host/port/name; supports postgres or sqlite)
+  - `DB_ENGINE` (forces sqlite when set to sqlite/sqlite3)
+  - `DJANGO_FORCE_POSTGRES` (force Postgres even in debug)
+  - `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT` (used when `DATABASE_URL` not provided)
+  - `USE_SQLITE` and `SQLITE_NAME` (explicit sqlite override)
+- CORS/hosts:
+  - CORS origins are hardcoded; no env toggle beyond `DEBUG`. Trusted CSRF origins are static in settings.
+- Auth/JWT:
+  - `JWT_SECRET_KEY` (defaults to `SECRET_KEY`)
+  - `JWT_ALGORITHM` (defaults to HS256)
+  - `JWT_ACCESS_TOKEN_EXPIRY` (timedelta in settings; default 15 minutes)
+  - `JWT_REFRESH_TOKEN_EXPIRY` (default 30 days)
+- Celery/Redis:
+  - `CELERY_BROKER_URL` (defaults to `redis://{REDIS_HOST}:{REDIS_PORT}/0`)
+  - `CELERY_RESULT_BACKEND` (defaults to same as broker)
+  - `REDIS_HOST`, `REDIS_PORT` (defaults redis:6379)
+  - `REDIS_SENTINEL_ENABLED` (when true, adds sentinel backend options)
+  - `REDIS_SSL_ENABLED` (enables Redis backend SSL)
+- Feature/config paths:
+  - `PUBLISH_SYNC_LOG_DIR` is derived; no env override.
+- Payments:
+  - `STRIPE_PUBLIC_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`
+  - `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_API_BASE` (defaults to sandbox base)
+- Rate limiting and throttles:
+  - Scopes are defined in settings; toggling is via `IGNY8_DEBUG_THROTTLE`.
+- Security/Cookies:
+  - `USE_SECURE_COOKIES`, `USE_SECURE_PROXY_HEADER` control secure cookie and proxy behavior.
+
+## Data Structures / Models Involved (no code)
+- None; variables configure runtime services used by auth, database, Celery, and billing.
+
+## Execution Flow
+- Django reads env vars at import of `settings.py`; defaults apply when unset.
+- Token helpers read JWT secrets/algorithms/expiries for generation and validation.
+- Celery settings are consumed by workers/beat at startup.
+
+## Cross-Module Interactions
+- Auth stack uses JWT settings and secrets.
+- Account middleware uses plan validation; DB settings drive tenancy storage.
+- Celery settings affect AI/automation/publishing/billing tasks.
+- Stripe/PayPal keys are consumed by billing modules.
+
+## State Transitions (if applicable)
+- Changes to env vars take effect on process restart; token expiry/secret changes invalidate existing tokens accordingly.
+
+## Error Handling
+- Missing/invalid DB env falls back to defaults (SQLite in debug unless forced).
+- Missing JWT secret falls back to `SECRET_KEY`; an absent secret raises errors during decode if unset.
+
+## Tenancy Rules
+- Env vars do not alter tenancy logic; they configure infrastructure supporting it.
+
+## Billing Rules (if applicable)
+- Stripe/PayPal keys must be present for payment webhooks/operations; plan enforcement itself is not env-driven.
+
+## Background Tasks / Schedulers (if applicable)
+- Celery broker/backend URLs and Redis options come from env; task timeouts and serializer are fixed in settings.
+
+## Key Design Considerations
+- Favor explicit env configuration for production (secrets, DB, Redis, Stripe/PayPal).
+- Keep debug-only flags (`DEBUG`, `IGNY8_DEBUG_THROTTLE`) off in production.
+- Use `DATABASE_URL` for portability; fallback logic supports sqlite for local dev.
+
+## How Developers Should Work With This Module
+- Set required secrets (`SECRET_KEY`, `JWT_SECRET_KEY`, Stripe/PayPal keys) before deploying.
+- Choose DB via `DATABASE_URL` or explicit `DB_*` vars; avoid sqlite in production unless intentional.
+- Configure Redis URLs for Celery in non-dev environments.
+- Restart services after changing env vars to apply new configuration.

docs/90-ARCHIVED/master-docs-original/00-system/07-MULTITENANCY-ACCESS-REFERENCE.md

@@ -0,0 +1,104 @@
+# Multi-Tenancy & Access Reference (Current State)
+
+## Purpose
+Authoritative map of tenant isolation, role access, and payment/API-key handling across the stack. Built from code as of Dec 2025.
+
+## Core Enforcement Points (backend)
+- Middleware:
+  - `backend/igny8_core/auth/middleware.py` (`AccountContextMiddleware`, ~L1-L220): resolves `request.account` from JWT/API key; blocks inactive/suspended accounts.
+  - `backend/igny8_core/middleware/request_id.py` (~L1-L70): request ID (not tenancy).
+  - `backend/igny8_core/middleware/resource_tracker.py` (~L1-L170): metrics (not tenancy).
+- Base viewsets:
+  - `backend/igny8_core/api/base.py` (`AccountModelViewSet`, ~L1-L240): filters by `request.account`; admin/developer/system overrides; sets account on create.
+  - `backend/igny8_core/api/base.py` (`SiteSectorModelViewSet`, ~L238-L430): additionally filters by site/sector and user’s accessible sites (SiteUserAccess) unless admin/developer/system.
+- Permissions:
+  - `backend/igny8_core/api/permissions.py`:
+    - `IsAuthenticatedAndActive`, `HasTenantAccess` (default in settings).
+    - `IsViewerOrAbove`, `IsEditorOrAbove`, `IsAdminOrOwner`.
+    - `IsSystemAccountOrDeveloper` (system/admin for integrations).
+  - Module-specific permissions also appear in `backend/igny8_core/auth/permissions.py` (legacy IsOwnerOrAdmin, IsEditorOrAbove, IsViewerOrAbove, AccountPermission).
+- Settings defaults:
+  - `backend/igny8_core/settings.py` REST_FRAMEWORK `DEFAULT_PERMISSION_CLASSES` = `IsAuthenticatedAndActive` + `HasTenantAccess`.
+  - Auth order: APIKeyAuthentication → JWTAuthentication → CSRFExemptSessionAuthentication → BasicAuth.
+  - Throttling: `DebugScopedRateThrottle` bypasses throttles for authenticated users/system/debug.
+- Models with enforced account/site/sector:
+  - Base models `AccountBaseModel`, `SiteSectorBaseModel` in `backend/igny8_core/auth/models.py` (top of file).
+
+## Flow (text flowchart)
+```
+Request
+  -> Middleware: AccountContextMiddleware sets request.account (JWT/API key), validates account status/plan
+  -> DRF Auth: APIKey/JWT/Session
+  -> Permissions: IsAuthenticatedAndActive + HasTenantAccess (+ role-specific)
+  -> ViewSet:
+       AccountModelViewSet filters by account
+       SiteSectorModelViewSet filters by account + site/sector + SiteUserAccess
+  -> Action-specific role checks (IsEditorOrAbove, IsAdminOrOwner, IsSystemAccountOrDeveloper)
+  -> Business logic (services) + credit checks (billing)
+  -> Response
+```
+
+## Module Access (backend ViewSets & guards)
+- Accounts/Users/Plans/Subscriptions:
+  - `auth/views.py`: `UsersViewSet`, `AccountsViewSet`, `SubscriptionsViewSet`, `SiteUserAccessViewSet` (account-scoped via AccountModelViewSet + role guards).
+  - Roles: owner/admin (or developer/system) can manage; others limited to self (UsersViewSet get_queryset).
+- Sites/Sectors:
+  - `auth/views.py` (`SiteViewSet`, `Sector` actions): SiteSectorModelViewSet enforces account + site/sector + SiteUserAccess; public slug read is AllowAny for active site slug only.
+- Planner:
+  - `modules/planner/views.py` (KeywordViewSet, ClusterViewSet, ContentIdeasViewSet) inherit SiteSectorModelViewSet; require site_id/sector_id; role: typically editor+ for writes.
+- Writer:
+  - `modules/writer/views.py` (TasksViewSet, ContentViewSet, ImagesViewSet, ContentTaxonomyViewSet) inherit SiteSectorModelViewSet; site/sector scoping; editor+ for writes.
+- Automation:
+  - `business/automation/views.py` (AutomationViewSet) inherits AccountModelViewSet/SiteSectorModelViewSet patterns; requires site_id for run/config; role: editor+ for mutate.
+- System settings (non-integrations):
+  - `modules/system/views.py` / `settings_views.py`: AccountModelViewSet; role usually admin/owner; authenticated + tenant required.
+- Integrations (OpenAI/Runware API keys):
+  - `modules/system/integration_views.py`: guarded by `IsSystemAccountOrDeveloper` (system account or developer only); tenant-scoped but effectively system-only for keys.
+- Billing:
+  - `modules/billing/views.py`: AccountModelViewSet; `IsAdminOrOwner` for credit transactions/payment methods; balance/usage requires auth + tenant.
+- Payments/Payment Methods:
+  - Payment methods: `AccountPaymentMethodViewSet` account-scoped; IsAuthenticated; default selection per account; admin/owner should manage.
+  - Payments: `PaymentViewSet` account-scoped; IsAuthenticated; list/available_methods/manual payment for current account only.
+
+## Frontend Guards
+- Route protection: `ProtectedRoute` (auth required, checks account/plan/payment methods), `ModuleGuard` (module enabled), `AdminGuard` (integration/admin pages only for system account or developer).
+- Sidebar hides Integration for non-system/developer; admin section shown only for system/developer.
+
+## AI Key Resolution
+- `ai/ai_core.py` `_load_account_settings`: tries tenant IntegrationSettings → system account IntegrationSettings (`aws-admin`/`default-account`/`default`) → Django settings (`OPENAI_API_KEY`, `RUNWARE_API_KEY`). All users run AI with shared keys if tenant keys absent.
+
+## Throttling
+- `api/throttles.py` `DebugScopedRateThrottle`: bypass for authenticated users/system/debug; per-scope rates in `settings.py`. Prevents 429s for normal users.
+
+## Payment / Billing Workflow (happy path)
+1) User authenticates (JWT) → request.account set.
+2) Payment methods (account-scoped) fetched via `/v1/billing/payment-methods/available/`; admin/owner can CRUD `/v1/billing/payment-methods/`.
+3) Invoices/Payments via billing endpoints (account-scoped; admin/owner).
+4) Credits used via CreditService on AI/automation calls (backend).
+
+## Access Summary by Role (runtime enforcement)
+- Viewer: read-only where viewsets allow `IsViewerOrAbove`; no writes.
+- Editor: can write planner/writer/automation; cannot manage billing/integration.
+- Admin/Owner: manage account/team/billing/payment methods; full module writes.
+- Developer/System account: cross-tenant overrides in some base filters; integration settings and admin menus.
+
+## Key Files (with line bands)
+- Middleware: `auth/middleware.py` (~L1-220)
+- Base viewsets: `api/base.py` (~L1-430)
+- Permissions: `api/permissions.py` (~L1-200), `auth/permissions.py` (~L1-120)
+- Settings (REST/Throttle): `settings.py` (REST_FRAMEWORK block, ~L200-360)
+- AI core key loading: `ai/ai_core.py` (~L1-120)
+- Integration settings views: `modules/system/integration_views.py` (~L1-300 main guards; actions throughout)
+- Planner views: `modules/planner/views.py` (all ViewSets inherit SiteSectorModelViewSet)
+- Writer views: `modules/writer/views.py`
+- Automation: `business/automation/views.py`, `services/automation_service.py`
+- Billing: `modules/billing/views.py`, `business/billing/services/credit_service.py`
+- Payment methods: `modules/billing/views.py` AccountPaymentMethodViewSet
+- Frontend guards: `src/components/auth/ProtectedRoute.tsx`, `src/components/auth/AdminGuard.tsx`, `src/components/common/ModuleGuard.tsx`
+- Sidebar gating: `src/layout/AppSidebar.tsx`
+
+## Open Items / Risks
+- Ensure public endpoints explicitly override default permissions (e.g., auth register/login, site slug read).
+- Validate all viewsets still inherit AccountModelViewSet/SiteSectorModelViewSet after future changes.
+- Add automated tests for cross-tenant denial, role gates, plan limits, and integration access.***
+

docs/90-ARCHIVED/master-docs-original/10-backend/00-BACKEND-ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# Backend Architecture
+
+## Purpose
+Explain how the backend is structured, wired, and executed across Django/DRF, middleware, routing, async processing, and logging.
+
+## Code Locations (exact paths)
+- Settings and app wiring: `backend/igny8_core/settings.py`
+- URL routing: `backend/igny8_core/urls.py`
+- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/middleware/resource_tracker.py`
+- Auth stack: `backend/igny8_core/api/authentication.py`, `backend/igny8_core/auth/utils.py`
+- Base viewsets and unified responses: `backend/igny8_core/api/base.py`
+- Domain models: `backend/igny8_core/auth/models.py` plus `backend/igny8_core/business/*/models.py`
+- Async/Celery config: `backend/igny8_core/settings.py`
+- Logging: `backend/igny8_core/settings.py` (publish/webhook logs), automation logging (`backend/igny8_core/business/automation/services/automation_logger.py`)
+
+## High-Level Responsibilities
+- Django/DRF API surface under `/api/v1/*` for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
+- Middleware establishes request IDs, tenant context, and optional resource tracking before views run.
+- DRF configuration standardizes pagination, filtering, authentication, throttling, and exception handling.
+- Celery + Redis provide async execution for AI, automation, publishing, and other long-running tasks.
+- Logging and CORS/security settings are centralized in settings.
+
+## Detailed Behavior
+- Apps registered in `INSTALLED_APPS` include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, publisher. Custom admin config is loaded first.
+- Middleware order: security → WhiteNoise → CORS → session/common/CSRF → Django auth → `RequestIDMiddleware` → `AccountContextMiddleware` (tenant + plan enforcement) → `ResourceTrackingMiddleware` (opt-in for admin/developer with header) → messages → clickjacking.
+- Routing (`urls.py`): admin plus CSV helpers for industries/seed keywords, then `/api/v1/` routers for auth, account, planner, writer, system, billing (user/admin), automation, linker, optimizer, publisher, integration. OpenAPI served at `/api/docs` and `/api/redoc`.
+- DRF defaults: unified exception handler (unless env disables), custom pagination, filtering/search/ordering, auth stack (API key → JWT → CSRF-exempt session → basic), scoped throttling per operation class, drf-spectacular schema generation with tag ordering.
+- CORS: IGNY8 domains and local dev ports allowed; credentials enabled; request/resource tracking headers exposed.
+- Celery: Redis broker/result; JSON serialization; task/soft time limits; single-prefetch; sentinel/SSL toggles via env.
+- Logging: console plus rotating files for publish/sync, WordPress API, webhooks; request IDs from middleware surface in responses; automation has dedicated file-based logger per run.
+
+## Data Structures / Models Involved (no code)
+- Tenancy/identity: `Account`, `Plan`, `Subscription`, `Site`, `Sector`, `User`, `SiteUserAccess`, `PasswordResetToken` (in auth models).
+- Domain models across planner, writer, billing, automation, publishing, integration, optimization (see domain models doc).
+- Middleware uses request-scoped `request.account`, `request.site`, and `request.request_id`.
+
+## Execution Flow
+1) Request enters middleware stack; IDs and tenant context are set; plan is verified.  
+2) DRF auth classes authenticate user/api-key/JWT/session.  
+3) Base viewsets filter by tenant/site/sector and handle unified responses.  
+4) Serializers validate; database writes enforce tenant alignment via model bases.  
+5) Optional Celery tasks are enqueued for long-running work; responses remain synchronous JSON with pagination/throttle headers when applicable.  
+6) Logging writes to configured handlers; request/resource IDs are added to responses.
+
+## Cross-Module Interactions
+- Tenant context from middleware is consumed by all module viewsets.  
+- AI and automation invoke Celery tasks and AI functions; billing services deduct credits used by automation/AI flows.  
+- Integration/publishing modules rely on API key auth to set `request.site` for WordPress and other platforms.
+
+## State Transitions (if applicable)
+- Account/plan validity is checked per request; system accounts are protected from deletion.  
+- Soft-delete is available on many models via `SoftDeletableModel`.  
+- Request lifecycle includes request ID creation, optional resource tracking, and unified response formatting.
+
+## Error Handling
+- Custom DRF exception handler wraps errors with `success=false`.  
+- `AccountContextMiddleware` blocks requests lacking account or active plan (403/402 JSON).  
+- Base viewsets wrap validation/404/500 errors into unified payloads.
+
+## Tenancy Rules
+- Request-level `account` (and `site`/`sector` where applicable) is injected by middleware/auth; base viewsets enforce filtering.  
+- Admin/developer/system-account users bypass tenant filtering; system accounts are guarded from deletion.
+
+## Billing Rules (if applicable)
+- Billing env keys configured in settings; plan enforcement occurs in middleware; credit debits handled by billing services during operations.
+
+## Background Tasks / Schedulers (if applicable)
+- Celery worker/beat use Redis URLs from settings; task limits and JSON serialization enforced.  
+- Automation, AI, publishing, and optimization tasks run async; automation logger writes per-run files.
+
+## Key Design Considerations
+- Middleware-first tenant enforcement ensures isolation.  
+- Unified API standards (responses, throttles, schema) keep clients consistent.  
+- Celery offloads expensive AI/automation/publishing work with bounded execution.  
+- Logging and request IDs aid observability; resource tracking is opt-in for admins.
+
+## How Developers Should Work With This Module
+- Register new apps in `INSTALLED_APPS` and route them under `/api/v1/*`.  
+- Use existing middleware order; add new middleware only if it does not break account/request ID handling.  
+- Inherit from base viewsets for scoping and response consistency.  
+- Use Celery for long-running tasks; respect Redis/task time-limit settings.  
+- Keep env vars (DB, JWT, Redis, Stripe/PayPal) set per `settings.py`; avoid hardcoded secrets.  

docs/90-ARCHIVED/master-docs-original/10-backend/01-DOMAIN-MODELS.md

@@ -0,0 +1,110 @@
+# 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.
+

docs/90-ARCHIVED/master-docs-original/10-backend/02-SERVICES-AND-MODULES.md

@@ -0,0 +1,96 @@
+# Services and Modules
+
+## Purpose
+Describe the backend service layer and module wiring that orchestrate domain models, AI/automation, billing, integration, and publishing.
+
+## Code Locations (exact paths)
+- Automation services: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`
+- Billing services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+- Integration service: `backend/igny8_core/business/integration/services/integration_service.py`
+- Additional service directories (see module-specific docs for details):
+  - Planner: `backend/igny8_core/business/planning/services/*`
+  - Content/Writer: `backend/igny8_core/business/content/services/*`
+  - Automation tasks: `backend/igny8_core/business/automation/tasks.py`
+  - Integration sync: `backend/igny8_core/business/integration/services/*`
+  - Publishing: `backend/igny8_core/business/publishing/services/*`
+  - Optimization: `backend/igny8_core/business/optimization/services/*`
+  - Linking: `backend/igny8_core/business/linking/services/*`
+
+## High-Level Responsibilities
+- Orchestrate multi-stage automation that chains planner and writer operations using AI and credits.
+- Manage credit pricing, balance checks, deductions, and ledger logging.
+- Generate invoices and handle billing documents.
+- Create, update, test, and list site integrations for external platforms.
+- Provide domain-specific service hooks for planner, writer, publishing, linking, and optimization flows (behavior documented in module-specific files).
+
+## Detailed Behavior
+### Automation
+- `AutomationService` enforces single concurrent run per site via cache lock, estimates required credits, checks account balance (with buffer), and creates an `AutomationRun`. It sequences stages (keywords→clusters, clusters→ideas, ideas→tasks/content, image prompt generation, image generation queue) using AI functions (`AutoClusterFunction`, `GenerateIdeasFunction`, `GenerateContentFunction`, `GenerateImagePromptsFunction`) through `AIEngine`, and the Celery image queue (`process_image_generation_queue`). It supports pause/cancel checks mid-stage, records partial progress, and advances `current_stage` with per-stage result JSON and credit tallies. Batch sizes and delays respect `AutomationConfig`.
+- `AutomationLogger` creates per-run directories (and optional shared mirrors), generates run IDs, writes main/stage logs, mirrors to shared folders when configured, and emits structured JSONL trace events for run start, progress, completion, and errors.
+
+### Billing
+- `CreditService` computes credit cost by first consulting `CreditCostConfig` (unit-aware for words/items/images) and falling back to constants. It checks balances, deducts credits atomically, updates account balance, writes `CreditTransaction`, and logs usage in `CreditUsageLog` with optional model/token metadata. It can also add credits and provides legacy check helpers.
+- `InvoiceService` generates invoice numbers per account/month, creates invoices for subscriptions or credit packages (adding line items and computing totals), supports custom invoices, and marks invoices paid or void. PDF generation is currently a placeholder.
+- `PaymentService` (see file) processes payments against invoices and updates statuses; details are documented in the module file.
+
+### Integration
+- `IntegrationService` creates, updates, deletes, fetches, and lists `SiteIntegration` records, setting account/site automatically. It can test connections per platform (WordPress, Shopify) and delegates to platform-specific test helpers inside the service; unimplemented platforms raise `NotImplementedError`. Credentials are set via `set_credentials`, which currently stores JSON as-is.
+- Additional sync services (`content_sync_service.py`, `sync_service.py`, `sync_metadata_service.py`, `sync_health_service.py`) coordinate publish/sync flows and health checks; see module docs for specifics.
+
+### Other Service Areas (structure)
+- Planner services (`clustering_service.py`, `ideas_service.py`) handle clustering/idea logic.
+- Content services (`content_generation_service.py`, `content_pipeline_service.py`, `metadata_mapping_service.py`, `validation_service.py`) manage content generation, pipelines, metadata mapping, and validation.
+- Publishing services (`publisher_service.py`, `deployment_service.py`, `adapters/`) manage publishing/deployment flows and destination adapters.
+- Optimization services (`analyzer.py`, `optimizer_service.py`) analyze and optimize content.
+- Linking services (`candidate_engine.py`, `injection_engine.py`, `linker_service.py`) prepare and apply link suggestions.
+- Automation tasks (`business/automation/tasks.py`) provide Celery entrypoints for automation runs.
+
+## Execution Flow
+- Automation: `AutomationService.start_automation` acquires lock → credit estimate/check → create `AutomationRun` → stage methods query planner/writer models, call AI functions via `AIEngine`, respect batch sizes/delays, and update run state/logs → credits are tallied from `AITaskLog` differences.
+- Billing: operations call `CreditService.check_*`/`deduct_*` before AI or content operations; invoices are created through `InvoiceService` and payments processed via `PaymentService`.
+- Integration: API endpoints invoke `IntegrationService` to persist integrations, retrieve lists, and run connection tests; sync services handle subsequent data movement.
+- Other domains: planner/content/publishing/linking/optimization services orchestrate their models and, where applicable, AI or external adapters; see domain docs for invocation points.
+
+## Cross-Module Interactions
+- Automation stages consume planner (Keywords/Clusters/ContentIdeas) and writer (Tasks/Content/Images) data and rely on credit usage logs from AI tasks.
+- Billing services are used by automation/AI flows to enforce credit availability and record deductions.
+- Integration services connect site data and publishing/sync flows to external platforms; publishing services depend on integration metadata when targeting destinations.
+- Planner/content services feed data used by publishing and optimization tasks.
+
+## State Transitions (if applicable)
+- Automation runs move through stages, can pause/cancel, and record partial progress with stage result JSON.
+- Credit balances mutate through add/deduct operations; transactions/usage logs capture each change.
+- Invoices progress through draft/pending/paid/void and payments through their status lifecycle.
+- Integrations toggle active/sync flags and update sync status/errors.
+
+## Error Handling
+- Automation: checks for concurrent runs; validates minimum keywords; pauses/cancels mid-stage; writes stage error messages; releases locks on failures.
+- Billing: raises when credit cost unknown or balance insufficient; wraps changes in atomic transactions.
+- Integration: platform test errors are logged and returned with `success=false`; unsupported platforms raise `NotImplementedError`.
+- Invoice service prevents voiding paid invoices and returns placeholder PDF until implemented.
+
+## Tenancy Rules
+- Services operate on tenant-scoped models; constructors typically receive account/site or derive them from models. Integration creation sets account from site; credit operations mutate `Account.credits`.
+- Privileged role bypass applies at the viewset layer; persisted records maintain account/site ownership.
+
+## Billing Rules (if applicable)
+- Costs resolved via `CreditCostConfig` (preferred) or constants; units can be per request, words (100/200), item, or image.
+- Deduct operations both adjust `Account.credits` and log to `CreditTransaction` and `CreditUsageLog`.
+- Invoice creation links to subscriptions or credit packages and uses account billing email/plan pricing.
+
+## Background Tasks / Schedulers (if applicable)
+- Automation uses Celery for image generation and may be triggered by scheduled runs (frequency/time in `AutomationConfig`).
+- Other long-running tasks (publishing, optimization, sync) are handled via their Celery tasks/adapters in respective service modules.
+
+## Key Design Considerations
+- Automation enforces exclusivity per site and accounts for credit sufficiency before starting.
+- Logging (AutomationLogger) produces per-run artifacts and structured traces for observability.
+- Credit handling is centralized to keep ledger and usage logs consistent and atomic.
+- Integration services abstract platform handling and allow per-platform test logic.
+
+## How Developers Should Work With This Module
+- Reuse `AutomationService` for running/continuing automation; respect locks and stage APIs.
+- Use `CreditService` before AI/content-heavy operations to check/deduct/add credits and to log usage.
+- Create invoices via `InvoiceService` helpers rather than constructing manually; update invoice/payment status through service methods.
+- Manage integrations through `IntegrationService` (create/update/test/list) and extend platform-specific tests as needed.
+- For domain-specific flows (planner/content/publishing/linking/optimization), place orchestration in the existing service modules and keep tenant context explicit.

docs/90-ARCHIVED/master-docs-original/10-backend/automation/AUTOMATION-LOGGING.md

@@ -0,0 +1,62 @@
+# Automation Logging
+
+## Purpose
+Explain how automation runs are logged, where artifacts are written, and how logs are retrieved via API.
+
+## Code Locations (exact paths)
+- Logger implementation: `backend/igny8_core/business/automation/services/automation_logger.py`
+- Service usage: `backend/igny8_core/business/automation/services/automation_service.py`
+- API exposure: `backend/igny8_core/business/automation/views.py` (`logs` action)
+- Run metadata: `backend/igny8_core/business/automation/models.py`
+
+## High-Level Responsibilities
+- Create per-run directories and log files for automation runs (primary and optional shared mirror).
+- Record stage-level start/progress/complete events and structured traces.
+- Provide tail retrieval of logs through an API endpoint.
+
+## Detailed Behavior
+- `AutomationLogger`:
+  - On `start_run`: generates `run_id` (`run_YYYYMMDD_HHMMSS_<trigger>`), creates run directory under `base_log_dir` (default `/data/app/logs/automation`), and optionally mirrors to `shared_log_dir` when configured. Initializes `automation_run.log` with run metadata and writes a JSONL trace entry (`run_trace.jsonl`).
+  - `log_stage_start`: appends to main log and writes a stage-specific log file `stage_<n>.log`; mirrors to shared dir if configured; writes a trace event (`stage_start` with pending count).
+  - `log_stage_progress`: appends progress lines to main and stage logs (and mirrored copies), and writes a `stage_progress` trace event.
+  - `log_stage_complete`: writes completion info with processed count, time elapsed, credits used to main/stage logs; emits trace (`stage_complete`).
+  - `log_stage_error`: writes error lines to logs and emits an error trace.
+  - `append_trace`: helper used by the service for per-item events; appends JSONL entries.
+  - `get_activity_log`: reads and returns the tail of `automation_run.log` (used by API).
+- `AutomationService` uses the logger at every stage boundary and significant progress point; also logs warnings/errors and mirrors events via the logger’s trace helpers.
+- Stage result data is stored in `AutomationRun.stage_n_result` JSON fields alongside logs, providing structured state in the DB.
+
+## Data Structures / Models Involved (no code)
+- `AutomationRun`: stores per-stage result JSON and run status used to correlate with log files.
+
+## Execution Flow
+- Run start → `start_run` creates directories/files → each stage emits start/progress/complete/error logs and traces → API `logs` endpoint reads `automation_run.log` tail for a given `run_id`.
+
+## Cross-Module Interactions
+- Logging uses the automation run/account/site context; no external modules write to these files. AI stages provide progress data; billing is inferred from AI task logs but not logged here.
+
+## State Transitions
+- Log files accumulate throughout a run; traces document run lifecycle events. Completion or failure is also reflected in `AutomationRun` status/results.
+
+## Error Handling
+- Logger operations are best-effort; exceptions during file/trace writes are swallowed to avoid breaking the run.
+- API `logs` returns 404 if the run does not exist; otherwise returns the requested number of lines.
+
+## Tenancy Rules
+- Run directories are keyed by account/site/run; API access is constrained by site ownership through the viewset query for `AutomationRun`.
+
+## Billing Rules
+- None directly; credit use is recorded in stage result JSON and inferred from AI task logs, not in the file logs.
+
+## Background Tasks / Schedulers
+- Logging occurs inside Celery-executed stages; no separate scheduled logging tasks.
+
+## Key Design Considerations
+- File-based logs per run make multi-stage processes auditable and debuggable without DB bloat.
+- Optional shared log dir supports centralized aggregation when multiple containers run workers.
+- JSONL traces allow machine parsing for UI status feeds while text logs support human debugging.
+
+## How Developers Should Work With This Module
+- When adding stage steps, emit progress via `AutomationLogger` to keep observability consistent.
+- Keep log writes best-effort; do not raise from logger helpers.
+- Ensure any new API log endpoints read from the same per-run directory structure and remain site/account scoped.

docs/90-ARCHIVED/master-docs-original/10-backend/automation/AUTOMATION-MODULE-REFERENCE.md

@@ -0,0 +1,91 @@
+# Automation Module Reference
+
+## Purpose
+Document how the automation module orchestrates multi-stage AI pipelines, exposes API endpoints, enforces tenancy/credits, and manages runs, configs, and logging.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/automation/models.py`
+- Services: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`
+- Tasks (Celery): `backend/igny8_core/business/automation/tasks.py`
+- API views and routing: `backend/igny8_core/business/automation/views.py`, `urls.py`
+- Supporting AI functions: `backend/igny8_core/ai/functions/auto_cluster.py`, `generate_ideas.py`, `generate_content.py`, `generate_image_prompts.py`, image queue in `backend/igny8_core/ai/tasks.py`
+- Tenancy/auth context: `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/api/base.py`
+
+## High-Level Responsibilities
+- Maintain per-site automation configs (batch sizes, delays, schedule, enable flag) and track run state with detailed per-stage results.
+- Provide APIs to configure, trigger, pause/resume/cancel, inspect, and log automation runs.
+- Execute seven sequential stages that transform planner/writer data via AI and local operations, with credit checks and pause/cancel handling.
+- Enforce tenant/site scoping on all automation resources and API operations.
+
+## Detailed Behavior
+- `AutomationConfig` stores enablement, frequency, scheduled time, batch sizes for stages 1–6, and within/between-stage delays. Config is created lazily per site.
+- `AutomationRun` captures run metadata: trigger type (manual/scheduled), status (`running/paused/cancelled/completed/failed`), current stage, pause/cancel timestamps, per-stage JSON results, total credits used, and error message.
+- `AutomationService` orchestrates the pipeline:
+  - Locks per site via cache (`automation_lock_{site.id}`) to prevent concurrent runs.
+  - Estimates credits before start and requires a 20% buffer over the estimate against `Account.credits`.
+  - Creates `AutomationRun` with generated `run_id` and logs start via `AutomationLogger`.
+  - Executes stages in order; each stage logs start/progress/complete, applies within/between-stage delays from config, and writes stage result JSON (counts, credits, timestamps, partial flags).
+  - Pause/cancel checks occur inside loops; state is persisted so resumed runs continue from the recorded stage.
+  - Stage credit usage is derived from AI task logs difference before/after the stage.
+- API layer (`AutomationViewSet`):
+  - `config`/`update_config` read/write `AutomationConfig` for a given `site_id` (scoped to the user’s account).
+  - `run_now` triggers `AutomationService.start_automation` and enqueues Celery `run_automation_task`.
+  - `current_run`, `history`, `logs`, `current_processing`, `estimate`, `pipeline_overview` expose run status, history, logs, credit estimates, and per-stage pending counts.
+  - `pause`, `resume`, `cancel` endpoints update run status and enqueue resume tasks when needed.
+- Celery tasks:
+  - `check_scheduled_automations` scans enabled configs hourly and triggers runs when frequency/time matches and no recent run exists.
+  - `run_automation_task` performs full pipeline execution.
+  - `resume_automation_task`/`continue_automation_task` continue a paused run from its recorded stage.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`, `AutomationRun` (automation state).
+- Planner models: `Keywords`, `Clusters`, `ContentIdeas`.
+- Writer models: `Tasks`, `Content`, `Images`.
+- AI task log (`AITaskLog`) for credit usage measurement.
+- Tenancy entities: `Account`, `Site` (scoping every query).
+
+## Execution Flow
+- API call → DRF auth → tenant/site resolved → viewset method → `AutomationService` operations → Celery task (for long-running execution).
+- Pipeline stages run in-process inside Celery workers, reading planner/writer data, invoking AI functions, updating models, logging progress, and writing stage results to `AutomationRun`.
+- Completion (or failure) updates run status and releases the site lock.
+
+## Cross-Module Interactions
+- Planner/writer models supply inputs and receive outputs (clusters, ideas, tasks, content, images).
+- AI engine executes clustering, idea generation, content generation, and image prompt generation; image rendering uses the AI image queue.
+- Billing credits are checked against `Account.credits`; credit usage is inferred from AI task logs (deduction logic handled in billing services when those AI calls occur).
+- Integration/publishing modules consume content/images produced downstream (outside automation).
+
+## State Transitions
+- Run status moves through `running` → (`paused`/`cancelled`/`failed`/`completed`); `current_stage` increments after each stage finishes; partial flags and timestamps mark mid-stage exits.
+- Config changes take effect on the next run; pause/resume toggles update run timestamps.
+
+## Error Handling
+- Start blocks if a run is already active for the site or cache lock is held.
+- Stage loops log and continue on per-batch/item errors; pause/cancel results are persisted mid-stage.
+- Failures in Celery run mark `AutomationRun` as failed, store error message, timestamp completion, and release the lock.
+- API endpoints return 400 for missing params or invalid state transitions, 404 for unknown runs, 500 on unexpected errors.
+
+## Tenancy Rules
+- All automation queries filter by `site` tied to the authenticated user’s `account`; config/run creation sets `account` and `site` explicitly.
+- API endpoints fetch `Site` with `account=request.user.account`; automation locks are per site.
+- No cross-tenant access; privileged role bypass is handled by DRF auth/permissions upstream.
+
+## Billing Rules
+- Start requires `Account.credits` ≥ 1.2× estimated credits; otherwise a 400 is returned.
+- Credits actually deducted by AI tasks are reflected via AI task logs and billing services (outside this module); automation aggregates usage per stage in `AutomationRun`.
+
+## Background Tasks / Schedulers
+- Hourly `check_scheduled_automations` respects config frequency/time and last run; skips if a run is already active.
+- Pipeline execution and resume steps run inside Celery tasks; within-stage sleeps apply delays from config.
+
+## Key Design Considerations
+- Single-run-per-site enforced via cache lock to prevent overlapping credit use or data contention.
+- Pause/resume/cancel is cooperative, checked inside stage loops, with partial results persisted.
+- Stage-by-stage logging and result JSON make pipeline progress observable and resumable.
+- Configurable batch sizes and delays balance throughput and API/credit usage.
+
+## How Developers Should Work With This Module
+- Use `AutomationService.start_automation` for new runs; never bypass the cache lock or credit check.
+- When extending stages, preserve pause/cancel checks, result recording, and credit delta calculation.
+- Add new API actions through `AutomationViewSet` if they manipulate automation state; keep site/account scoping.
+- For new schedulers, reuse the lock pattern and `AutomationConfig` fields, and update `next_run_at` appropriately.

docs/90-ARCHIVED/master-docs-original/10-backend/automation/AUTOMATION-PIPELINE-STAGES.md

@@ -0,0 +1,102 @@
+# Automation Pipeline Stages
+
+## Purpose
+Detail the seven pipeline stages executed by `AutomationService`, including inputs, queries, validations, delays, credit handling, and state recording.
+
+## Code Locations (exact paths)
+- Orchestration: `backend/igny8_core/business/automation/services/automation_service.py`
+- Models: `backend/igny8_core/business/automation/models.py`
+- AI functions: `backend/igny8_core/ai/functions/auto_cluster.py`, `generate_ideas.py`, `generate_content.py`, `generate_image_prompts.py`
+- Image queue: `backend/igny8_core/ai/tasks.py` (`process_image_generation_queue`)
+- Stage entrypoints: `backend/igny8_core/business/automation/tasks.py` (Celery `run_automation_task`, `resume_automation_task`)
+
+## High-Level Responsibilities
+- Execute a fixed seven-stage sequence that moves data from planner keywords through content with images and into manual review readiness.
+- Enforce batch sizes/delays from `AutomationConfig`, support pause/cancel, and write per-stage results into `AutomationRun`.
+- Track credit deltas per stage using AI task log counts.
+
+## Detailed Behavior
+Across all stages:
+- Each stage logs start/progress/complete via `AutomationLogger`, respects `within_stage_delay` between batches/items, and `between_stage_delay` between stages.
+- Pause/cancel is checked inside loops; on pause/cancel, the stage records partial counts, credits, elapsed time, and reason, then exits.
+- Credits used per stage are computed from `AITaskLog` count delta relative to stage start.
+
+### Stage 1: Keywords → Clusters (AI)
+- Input query: `Keywords` where `site=current`, `status='new'`, `cluster__isnull=True`, `disabled=False`.
+- Validation: `validate_minimum_keywords` requires at least 5 keywords; if not valid, stage is skipped with result noting skip reason and `current_stage` advances to 2.
+- Processing: Batch size = `stage_1_batch_size` (capped to total). For each batch, calls `AIEngine.execute(AutoClusterFunction, payload={'ids': batch})`; waits on task ID; logs per-batch progress. Errors are logged and skipped; pipeline continues.
+- Result: counts keywords processed, clusters created since run start, batches, credits used, time elapsed; sets `current_stage=2`.
+
+### Stage 2: Clusters → Ideas (AI)
+- Pre-check: warns if any `Keywords` still pending from Stage 1.
+- Input query: `Clusters` where `site=current`, `status='new'`, `disabled=False`.
+- Processing: Iterates clusters one-by-one; for each, calls `AIEngine.execute(GenerateIdeasFunction, payload={'cluster_id': cluster.id})`; waits on task ID; logs progress. Errors are logged and skipped.
+- Result: counts clusters processed, ideas created since run start, credits used, time elapsed; sets `current_stage=3`.
+
+### Stage 3: Ideas → Tasks (Local)
+- Pre-check: warns if clusters remain without ideas.
+- Input query: `ContentIdeas` where `site=current`, `status='new'`.
+- Processing: Batched by `stage_3_batch_size`. For each idea, builds keyword string (M2M keywords or `target_keywords`) and creates `Tasks` with queued status, copying account/site/sector, cluster, content type/structure, and description. Idea status set to `queued`.
+- Result: ideas processed, tasks created, batches, time elapsed (credits 0 because local); sets `current_stage=4`.
+
+### Stage 4: Tasks → Content (AI)
+- Pre-check: warns if `ContentIdeas` remain `new`.
+- Input query: `Tasks` where `site=current`, `status='queued'`.
+- Processing: Batched by `stage_4_batch_size`. Uses `GenerateContentFunction` via `AIEngine` per batch (payload contains task IDs). Waits on task IDs, logs progress, continues on errors. Tracks total words by summing generated content word_count.
+- Result: tasks processed, content created count, total_words, credits used, time elapsed; sets `current_stage=5`.
+
+### Stage 5: Content → Image Prompts (AI)
+- Input query: `Content` where `site=current`, `status='draft'`, with zero images (annotated count=0).
+- Processing: Batched by `stage_5_batch_size`. For each batch, calls `GenerateImagePromptsFunction` via `AIEngine` (payload content IDs). Waits on task IDs, logs progress; continues on errors.
+- Result: content processed, prompts created (from AI task logs), credits used, time elapsed; sets `current_stage=6`.
+
+### Stage 6: Image Prompts → Images (AI image queue)
+- Input query: `Images` where `site=current`, `status='pending'`.
+- Processing: Iterates pending images; for each, enqueues `process_image_generation_queue.delay(image_ids=[id], account_id, content_id)` when Celery is available, or calls directly in sync fallback. Waits on task IDs with continue-on-error to avoid blocking the stage. Logs progress per image; applies within-stage delay between images.
+- Result: images processed, images generated (status `generated` since run start), content moved to `review`, credits used, time elapsed; sets `current_stage=7`.
+
+### Stage 7: Manual Review Gate (Count-only)
+- Input query: `Content` where `site=current`, `status='review'`.
+- Processing: Counts review-ready content, logs IDs (truncated), marks run `status='completed'`, sets `completed_at`, and releases the site lock.
+- Result: ready_for_review count and content IDs stored in `stage_7_result`.
+
+## Execution Flow
+- Celery task `run_automation_task` instantiates `AutomationService.from_run_id` and calls stages 1→7 sequentially.
+- Stage transitions update `AutomationRun.current_stage`; between-stage delays applied via `between_stage_delay`.
+- Resume path (`resume_automation_task`) starts from the recorded `current_stage` and continues through remaining stages.
+
+## Cross-Module Interactions
+- Planner: Stage 1/2 use `Keywords`/`Clusters`; Stage 3 converts `ContentIdeas` into `Tasks`.
+- Writer: Stages 4–6 create `Content` and `Images` and move content toward review.
+- AI engine and functions are invoked in Stages 1, 2, 4, 5; Stage 6 uses the AI image queue.
+- Billing: Credits are consumed by AI calls; automation records deltas per stage from AI task logs.
+
+## State Transitions
+- `AutomationRun.status` moves to `completed` at Stage 7; can be set to `failed` on exceptions or `cancelled` via API; `paused` can be set mid-run and resumed.
+- `current_stage` increments after each successful stage; partial stage results include a `partial` flag and stop reason.
+- Domain models change status along the pipeline (`Keywords` → clusters, `Clusters` → ideas, `ContentIdeas` → queued/tasks, `Tasks` → completed/content, `Content` → draft/review, `Images` → generated).
+
+## Error Handling
+- Each stage logs errors and continues to next batch/item; pause/cancel checks short-circuit with partial results saved.
+- Task wait helper tolerates Celery backend errors; can continue on error when flagged.
+- Stage start may be skipped with explicit skip reason (e.g., insufficient keywords).
+
+## Tenancy Rules
+- All queries filter by `site` (and implicit account via tenancy bases); account/site set on created `Tasks` and inherited on `Images` and other records through model save hooks.
+- Locks and runs are per site; API scoping requires the authenticated user’s account to own the site.
+
+## Billing Rules
+- Start requires sufficient credits (1.2× estimate). Credits used are inferred from AI task log counts per stage; actual deductions occur in AI/billing services invoked by the AI functions.
+
+## Background Tasks / Schedulers
+- Entire stage chain runs inside Celery workers; within-stage sleeps respect config delays; between-stage sleeps applied after each stage.
+
+## Key Design Considerations
+- Idempotent, resume-capable progression with partial state persisted in `AutomationRun`.
+- Configurable batch sizes/delays mitigate rate limits and manage credit burn.
+- Continue-on-error semantics prevent single failures from stopping the pipeline while still recording issues.
+
+## How Developers Should Work With This Module
+- When modifying stages, keep pause/cancel checks, stage result recording, and credit delta calculation.
+- Add new AI stages by wiring through `AIEngine.execute` and the task wait helper; ensure queries are site-scoped and statuses updated.
+- For new items types, add pending queries and status transitions consistent with existing patterns.

docs/90-ARCHIVED/master-docs-original/10-backend/automation/AUTOMATION-SCHEDULER.md

@@ -0,0 +1,75 @@
+# Automation Scheduler
+
+## Purpose
+Describe how scheduled runs are detected, triggered, and resumed using Celery tasks and automation configs.
+
+## Code Locations (exact paths)
+- Celery tasks: `backend/igny8_core/business/automation/tasks.py`
+- Models: `backend/igny8_core/business/automation/models.py`
+- Service invoked: `backend/igny8_core/business/automation/services/automation_service.py`
+
+## High-Level Responsibilities
+- Periodically scan enabled automation configs to start scheduled runs.
+- Prevent overlapping runs per site via cache locks and active run checks.
+- Resume paused runs from their recorded stage.
+
+## Detailed Behavior
+- `check_scheduled_automations` (Celery, hourly):
+  - Iterates `AutomationConfig` with `is_enabled=True`.
+  - Frequency rules:
+    - `daily`: run when current hour matches `scheduled_time.hour`.
+    - `weekly`: run Mondays at the scheduled hour.
+    - `monthly`: run on the 1st of the month at the scheduled hour.
+  - Skips if `last_run_at` is within ~23 hours or if an `AutomationRun` with `status='running'` exists for the site.
+  - On trigger: instantiates `AutomationService(account, site)`, calls `start_automation(trigger_type='scheduled')`, updates `last_run_at` and `next_run_at` (via `_calculate_next_run`), saves config, and enqueues `run_automation_task.delay(run_id)`.
+  - Exceptions are logged per site; lock release is handled by the service on failure paths.
+- `run_automation_task`:
+  - Loads service via `from_run_id`, runs stages 1–7 sequentially.
+  - On exception: marks run failed, records error/completed_at, and deletes site lock.
+- `resume_automation_task` / alias `continue_automation_task`:
+  - Loads service via `from_run_id`, uses `current_stage` to continue remaining stages.
+  - On exception: marks run failed, records error/completed_at.
+- `_calculate_next_run`:
+  - Computes next run datetime based on frequency and `scheduled_time`, resetting seconds/microseconds; handles month rollover for monthly frequency.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`: contains schedule fields (`frequency`, `scheduled_time`, `last_run_at`, `next_run_at`, `is_enabled`).
+- `AutomationRun`: records run status/stage used during resume/failure handling.
+
+## Execution Flow
+1) Celery beat (or cron) invokes `check_scheduled_automations` hourly.  
+2) Eligible configs spawn new runs via `AutomationService.start_automation` (includes lock + credit check).  
+3) `run_automation_task` executes the pipeline asynchronously.  
+4) Paused runs can be resumed by enqueueing `resume_automation_task`/`continue_automation_task`, which restart at `current_stage`.  
+5) Failures set run status to `failed` and release locks.
+
+## Cross-Module Interactions
+- Uses planner/writer data inside the pipeline (see pipeline doc); billing/credits enforced at start.
+- Locking is done via Django cache, independent of other modules but prevents concurrent Celery runs per site.
+
+## State Transitions
+- Config timestamps (`last_run_at`, `next_run_at`) update on scheduled launch.
+- Run status changes to `failed` on task exceptions; to `completed` at stage 7; to `paused/cancelled` via API.
+
+## Error Handling
+- Scheduled start is skipped with log messages if recently run or already running.
+- Exceptions during run execution mark the run failed, record error message, set `completed_at`, and release the cache lock.
+
+## Tenancy Rules
+- Configs and runs are site- and account-scoped; scheduler uses stored account/site from the config; no cross-tenant scheduling.
+
+## Billing Rules
+- Start uses `AutomationService.start_automation`, which enforces credit sufficiency before scheduling the Celery execution.
+
+## Background Tasks / Schedulers
+- Hourly `check_scheduled_automations` plus the long-running `run_automation_task` and resume tasks run in Celery workers.
+
+## Key Design Considerations
+- Hourly scan with coarse matching keeps implementation simple while honoring per-site schedules.
+- Cache lock and active-run checks prevent double-starts from overlapping schedules or manual triggers.
+- Resume task reuses the same stage methods to keep behavior consistent between fresh and resumed runs.
+
+## How Developers Should Work With This Module
+- When adding new frequencies, extend `check_scheduled_automations` and `_calculate_next_run` consistently.
+- Ensure Celery beat (or an equivalent scheduler) runs `check_scheduled_automations` hourly in production.
+- Preserve lock acquisition and failure handling when modifying task flows to avoid orphaned locks.

docs/90-ARCHIVED/master-docs-original/10-backend/billing/BILLING-MODULE-REFERENCE.md

@@ -0,0 +1,98 @@
+# Billing Module Reference
+
+## Purpose
+Explain how billing is implemented: invoices, payments, credit packages, credit history/usage, payment methods, and limits, as exposed by billing services and API viewsets.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/billing/models.py`
+- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+- API (business billing): `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/business/billing/urls.py`
+- API (core billing endpoints): `backend/igny8_core/modules/billing/views.py`, `backend/igny8_core/modules/billing/urls.py`
+- Plan metadata (included credits/limits): `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
+
+## High-Level Responsibilities
+- Maintain credit ledger, usage logs, configurable per-operation costs, invoices, payments, credit packages, country-level payment method configs, and account-scoped payment methods.
+- Expose endpoints for invoices/payments/credit packages/transactions, credit balance/usage/limits, and admin billing operations.
+- Deduct or add credits atomically while recording both transactions and usage logs.
+- Provide manual and (placeholder) Stripe/PayPal payment flows.
+
+## Detailed Behavior
+- Invoices (`InvoiceViewSet`):
+  - `list`/`retrieve`: fetch account-scoped invoices; include totals, line items, billing period, dates.
+  - `download_pdf`: returns PDF bytes from `InvoiceService.generate_pdf` (currently placeholder text payload).
+- Payments (`PaymentViewSet`):
+  - `list`: account-scoped payments with amounts, methods, status, invoice linkage, timestamps.
+  - `available_methods`: delegates to `PaymentService.get_available_payment_methods` (country/config-driven; returns methods plus metadata).
+  - `create_manual_payment`: creates a manual payment for an invoice (bank/local wallet); requires invoice_id, method, reference; rejects already-paid invoices; returns pending-approval status.
+- Account payment methods (`AccountPaymentMethodViewSet`):
+  - CRUD for account-level payment metadata (non-sensitive). `perform_create`/`perform_update` enforce one default by resetting others when `is_default` true or none exists.
+  - `set_default` toggles default within the account.
+- Credit packages (`CreditPackageViewSet`):
+  - `list`: active packages with credits/price/discount/featured/sort order.
+  - `purchase`: creates invoice via `InvoiceService.create_credit_package_invoice`; returns next action depending on requested payment method (`stripe`/`paypal` placeholders, manual fallback returns invoice info).
+- Credit transactions (`CreditTransactionViewSet` in business billing views; also registered under `credits/transactions` in URLs): lists credit ledger entries per account.
+- Core billing endpoints (`modules/billing/views.py`):
+  - `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month.
+  - `CreditUsageViewSet`: paginated credit usage logs with filters (operation_type, date range); `summary` aggregates by operation/model and totals (credits, USD); `limits` returns plan/account limits and usage (users/sites/etc.) based on `Plan` fields.
+- Routing (`business/billing/urls.py`):
+  - Routers for invoices, payments, credit packages, transactions, payment methods, and canonical credit endpoints (balance/usage/transactions). Legacy available-methods endpoint exposed at `/payment-methods/available/`.
+
+## Data Structures / Models Involved (no code)
+- `CreditTransaction`: ledger with type, amount (positive/negative), balance_after, metadata.
+- `CreditUsageLog`: per-AI-operation usage with operation_type, credits_used, cost_usd, model_used, tokens, related object references, metadata.
+- `CreditCostConfig`: per-operation cost config with unit, display metadata, active flag, audit of previous cost.
+- `Invoice`: invoice_number, status, amounts (subtotal/tax/total), currency, billing_period, line_items JSON, subscription link, payment metadata, timestamps.
+- `Payment`: status lifecycle, method (stripe/paypal/bank/local wallet/manual), provider references, manual notes/approval, failure reason, metadata.
+- `CreditPackage`, `PaymentMethodConfig` (country/method availability + instructions/bank/local wallet data), `AccountPaymentMethod` (account-scoped payment metadata).
+- Plan/account credits and limits: `Plan.included_credits`, `Plan.max_users/sites/industries/author_profiles`, `Account.credits`.
+
+## Execution Flow
+- Credits:
+  - Operations call `CreditService.get_credit_cost` → `check_credits`/`deduct_credits` or `deduct_credits_for_operation` → updates `Account.credits`, writes `CreditTransaction` and `CreditUsageLog`.
+  - Costs resolved from `CreditCostConfig` when active; otherwise constants. Units support per request, per 100/200 words, per item/image/idea.
+- Invoicing/Payments:
+  - Credit package purchase → invoice creation → next-action response (manual vs pending Stripe/PayPal integration).
+  - Manual payment submission → `PaymentService.create_manual_payment` persists pending approval.
+- Credit balance/usage:
+  - Balance endpoint computes plan credits and month-to-date usage (from `CreditUsageLog`).
+  - Usage endpoint filters logs; summary aggregates by operation/model and totals; limits endpoint computes plan-based limits and usage (users/sites/etc.) per account.
+
+## Cross-Module Interactions
+- AI/automation/planner/writer flows trigger credit checks/deductions through `CreditService`; usage logs can be filtered by operation_type (clustering, idea_generation, content_generation, image_generation, optimization, reparse).
+- Plan limits surfaced in billing limits endpoint affect account/user/site management elsewhere.
+- Invoice/payment metadata may be used by frontend billing UI; manual payments require admin follow-up.
+
+## State Transitions
+- Credits mutate `Account.credits`; ledger captures each change; usage logs accumulate per operation.
+- Invoices move through statuses (`draft/pending/paid/void/uncollectible`); payments through (`pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled`).
+- Credit packages and payment methods have active/default flags; cost configs can be toggled active/inactive.
+
+## Error Handling
+- Insufficient credits raise `InsufficientCreditsError`; API returns 402 when caught (e.g., content generation, credit deduct flows).
+- Manual payment rejects missing fields or already-paid invoices.
+- Usage/balance endpoints return empty data when account/plan missing instead of hard errors.
+- Validation errors on site/sector/account scoping propagate from base viewsets and model constraints.
+
+## Tenancy Rules
+- Account scoping enforced via `AccountModelViewSet` or explicit account filtering in viewsets; all billing data is per-account.
+- Payment methods, invoices, payments, transactions, usage logs, and balances are filtered to `request.user.account` (or `request.account` from middleware).
+- Plan data comes from the account’s associated plan; no cross-tenant visibility.
+
+## Billing Rules
+- Credit costs configurable via `CreditCostConfig`; fallback constants apply when no config.
+- Credit deductions and ledger entries are atomic; usage logs record the same operation with optional model/token metadata.
+- Balance endpoint includes plan monthly credits; limits endpoint reports plan/user/site limits but does not enforce them here.
+
+## Background Tasks / Schedulers
+- None specific to billing in this module; Stripe/PayPal integrations are placeholders. Any future webhooks should persist to these models and adjust credits/invoices/payments accordingly.
+
+## Key Design Considerations
+- Credit handling is centralized in `CreditService` to keep ledger and usage logs consistent.
+- Usage/balance endpoints are read-mostly, with graceful handling when plan/account data is missing.
+- Manual payments support bank/local wallet flows without storing sensitive data; account payment methods store display metadata only.
+
+## How Developers Should Work With This Module
+- Use `CreditService` for all credit checks/deductions/additions; do not mutate `Account.credits` directly.
+- When adding new AI operations, add `operation_type` to `CreditUsageLog.OPERATION_TYPE_CHOICES` and `CreditCostConfig` seed/constants, then use `deduct_credits_for_operation`.
+- Extend payment flows by implementing Stripe/PayPal handlers in `PaymentService` and wiring webhooks to update `Payment`/`Invoice`.
+- Use existing serializers/viewsets when exposing billing data; keep queries scoped to `request.account`.

docs/90-ARCHIVED/master-docs-original/10-backend/billing/CREDIT-SYSTEM.md

@@ -0,0 +1,80 @@
+# Credit System
+
+## Purpose
+Detail how credits are priced, checked, deducted, logged, and reported across the platform.
+
+## Code Locations (exact paths)
+- Credit logic: `backend/igny8_core/business/billing/services/credit_service.py`
+- Credit costs config: `backend/igny8_core/business/billing/models.py` (`CreditCostConfig`)
+- Ledger and usage logs: `backend/igny8_core/business/billing/models.py` (`CreditTransaction`, `CreditUsageLog`)
+- API endpoints: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`, `CreditUsageViewSet`)
+- Constants and exceptions: `backend/igny8_core/business/billing/constants.py`, `exceptions.py`
+- Plan included credits: `backend/igny8_core/auth/models.py` (`Plan.included_credits`, `Account.credits`)
+
+## High-Level Responsibilities
+- Compute operation costs (configurable per operation and unit) and enforce sufficient balance before AI/content actions.
+- Deduct or add credits atomically while writing both transaction and usage log records.
+- Provide balance, usage history, summaries, and limits endpoints for clients.
+- Allow admin-configurable cost overrides via `CreditCostConfig`.
+
+## Detailed Behavior
+- Cost resolution (`CreditService.get_credit_cost`):
+  - First checks `CreditCostConfig` for the operation (active records). Supports units: `per_request`, `per_100_words`, `per_200_words`, `per_item`, `per_image`. Applies amounts when provided (e.g., words, items, images).
+  - Falls back to hardcoded `CREDIT_COSTS` constants; raises `CreditCalculationError` for unknown operations.
+  - Legacy variable costs: content_generation per 100 words, optimization per 200 words, image_generation per image, idea_generation per idea.
+- Balance enforcement:
+  - `check_credits`/`check_credits_legacy` raise `InsufficientCreditsError` when balance insufficient.
+  - `deduct_credits_for_operation` computes cost, checks balance, builds a default description per operation when not supplied, then calls `deduct_credits`.
+- Deduction (`deduct_credits`):
+  - Atomic: decrements `Account.credits`, writes `CreditTransaction` with negative amount and balance_after, writes `CreditUsageLog` capturing operation_type, cost_usd/model/tokens/related object references, metadata.
+- Add credits (`add_credits`):
+  - Atomic: increments `Account.credits`, writes `CreditTransaction` with positive amount and balance_after.
+- Logging:
+  - `CreditTransaction` is the authoritative ledger; `CreditUsageLog` tracks per-operation usage for analytics and summaries.
+  - `CreditCostConfig` tracks `previous_cost` on save when cost changes.
+- Reporting endpoints (modules/billing):
+  - `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month (from `CreditUsageLog`), and remaining credits.
+  - `CreditUsageViewSet.list`: paginated usage logs filtered by operation_type and date range, account-scoped.
+  - `CreditUsageViewSet.summary`: aggregates credits and USD cost by operation and model over a date range (defaults to current month).
+  - `CreditUsageViewSet.limits`: returns plan limits (users/sites/industries/author profiles) and current usage counts, plus credits info; returns empty limits if account/plan missing.
+
+## Data Structures / Models Involved (no code)
+- `CreditCostConfig`: operation_type, credits_cost, unit, display_name, description, is_active, previous_cost, updated_by, timestamps.
+- `CreditTransaction`: transaction_type (purchase/subscription/refund/deduction/adjustment), amount (+/-), balance_after, description, metadata, reference_id, created_at.
+- `CreditUsageLog`: operation_type (clustering/idea_generation/content_generation/image_generation/reparse/legacy names), credits_used, cost_usd, model_used, tokens_in/out, related object type/id, metadata, created_at.
+- `Account.credits`: current balance; `Plan.included_credits`: monthly included credits.
+
+## Execution Flow
+- Caller requests an operation → `get_credit_cost` computes cost → `check_credits` ensures balance → `deduct_credits` mutates balance and writes ledger + usage → upstream operation proceeds (AI/content).
+- Balance/usage endpoints read from `Account`, `CreditUsageLog`, `Plan` to present current balances, month-to-date usage, summaries, and limits.
+
+## Cross-Module Interactions
+- AI/automation/planner/writer services call `CreditService` before expensive operations; automation aggregates credits used per stage from AI task logs, while billing logs capture actual deductions at AI call sites.
+- Plan limits (users/sites/industries/authors) referenced in billing limits endpoint inform account management elsewhere.
+
+## State Transitions
+- Balance changes recorded per transaction; usage accumulates per operation. Cost configs can be toggled active/inactive and updated with audit of previous cost.
+
+## Error Handling
+- Unknown operation types raise `CreditCalculationError`; insufficient balance raises `InsufficientCreditsError` (mapped to HTTP 402 in callers).
+- Balance/usage endpoints fall back to zeros/empty when account/plan missing rather than erroring.
+
+## Tenancy Rules
+- All credit operations and queries are account-scoped; viewsets filter by `request.account`/`request.user.account`. No cross-tenant access.
+
+## Billing Rules
+- Costs derived from `CreditCostConfig` > constants; units must match supplied amount. Ledger and usage logs are mandatory for every deduction/addition.
+
+## Background Tasks / Schedulers
+- None dedicated; credit usage often originates from AI Celery tasks but logging happens at the service call site.
+
+## Key Design Considerations
+- Centralized credit math and atomic DB updates prevent drift between balance, ledger, and usage logs.
+- Configurable costs allow runtime tuning without code changes.
+- Reporting endpoints are read-only and tolerant of missing plan data to keep dashboards resilient.
+
+## How Developers Should Work With This Module
+- Always route credit checks/deductions/additions through `CreditService`.
+- When adding new AI operations, register operation_type in `CreditUsageLog`/constants and optionally seed `CreditCostConfig`.
+- Include amount (words/items/images) when calling `deduct_credits_for_operation` so unit-based pricing applies.
+- Use balance/usage endpoints for UI/analytics; avoid custom queries that bypass account scoping.

docs/90-ARCHIVED/master-docs-original/10-backend/billing/PRICING-AND-PLANS.md

@@ -0,0 +1,68 @@
+# Pricing and Plans
+
+## Purpose
+Describe how plans and pricing are represented in the backend and how plan data is used for credits and limits.
+
+## Code Locations (exact paths)
+- Plan and account fields: `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
+- Billing limits endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditUsageViewSet.limits`)
+- Credit balance endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`)
+
+## High-Level Responsibilities
+- Define subscription plans with included credits, billing cycle, pricing, feature flags, account limits, and Stripe metadata.
+- Attach plans to accounts and expose plan-based limits and credits to billing endpoints.
+- Keep credit computations aligned with `included_credits` via `Plan.get_effective_credits_per_month`.
+
+## Detailed Behavior
+- `Plan` fields:
+  - Pricing: `price`, `billing_cycle` (`monthly/annual`), `extra_credit_price`, `allow_credit_topup`, optional auto-topup thresholds/amounts.
+  - Credits: `included_credits` (preferred) with legacy `credits_per_month` fallback via `get_effective_credits_per_month`.
+  - Limits: `max_users`, `max_sites`, `max_industries`, `max_author_profiles`.
+  - Stripe: `stripe_product_id`, `stripe_price_id`.
+  - Features: JSON `features` list; `is_active` flag.
+  - Validation ensures `max_sites >= 1`, `included_credits >= 0`.
+- `Account` fields:
+  - `plan` FK, `credits` balance, status (active/suspended/trial/cancelled), billing contact/address fields, tax_id, retention days, Stripe customer id.
+  - Soft-delete guard prevents deleting system accounts.
+- Limits computation (billing `limits` endpoint):
+  - Calculates current usage counts (users, sites, industries, author profiles) and returns alongside plan limits.
+  - Returns empty limits when account or plan is missing to keep UI resilient.
+- Credit balance:
+  - Balance endpoint includes `plan_credits_per_month` using `Plan.get_effective_credits_per_month`.
+
+## Data Structures / Models Involved (no code)
+- `Plan`, `Account` (plan attachment, credits, limits, billing info).
+
+## Execution Flow
+- Account creation/association sets `plan`; credit balance endpoints read plan credits and account credits.
+- Limits endpoint reads plan limits and computes current usage counts per account.
+- Credit usage/deductions run against `Account.credits`; top-ups/invoices handled through billing services.
+
+## Cross-Module Interactions
+- Billing endpoints surface plan credits and limits; credit cost/deductions happen in billing services.
+- Automation start checks `Account.credits` but not plan limits; plan status enforced in `AccountContextMiddleware` (requires active plan).
+
+## State Transitions
+- Plan activation toggles `is_active`; account plan changes immediately affect limits/balance reporting.
+- Account status/plan changes enforced at middleware for access gating.
+
+## Error Handling
+- Plan validation errors for invalid limits/credits on save; billing endpoints return empty limits when plan/account missing instead of failing.
+
+## Tenancy Rules
+- Plans are global; accounts reference a single plan. All limit calculations are per account.
+
+## Billing Rules
+- Credits included per plan reported via balance endpoint; extra credit price/top-up fields are present but actual purchase flows are through credit packages/invoices (not auto-charging in code shown).
+
+## Background Tasks / Schedulers
+- None specific to plans; any subscription renewal logic would generate invoices/payments via billing services (not implemented here).
+
+## Key Design Considerations
+- `included_credits` supersedes legacy `credits_per_month`; keep `get_effective_credits_per_month` for backward compatibility.
+- Limits are informational in the billing module; enforcement must occur in the respective domains if required.
+
+## How Developers Should Work With This Module
+- When adding new plan features or limits, extend `Plan` fields and ensure billing limits endpoint surfaces them.
+- Use `get_effective_credits_per_month` wherever plan credits are displayed or calculated.
+- Keep plan validation consistent (non-negative credits, minimum site/user counts).

docs/90-ARCHIVED/master-docs-original/10-backend/integrations/THIRD-PARTY-SERVICES.md

@@ -0,0 +1,85 @@
+# Third-Party Services (Integrations)
+
+## Purpose
+Document how site-level integrations are modeled and exposed via API, including WordPress connection testing, sync, and metadata updates.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/integration/models.py` (`SiteIntegration`, `SyncEvent`)
+- Services: `backend/igny8_core/business/integration/services/integration_service.py`, `sync_service.py`, `sync_metadata_service.py`, `sync_health_service.py`, `content_sync_service.py`
+- API views and routing: `backend/igny8_core/modules/integration/views.py`, `backend/igny8_core/modules/integration/urls.py`
+- Webhooks: `backend/igny8_core/modules/integration/webhooks.py`
+
+## High-Level Responsibilities
+- Store per-site integration configs and credentials for platforms (WordPress, Shopify, custom).
+- Provide CRUD, test-connection, sync, sync-status, and structure-update endpoints for integrations.
+- Track sync events for debugging/monitoring.
+- Enforce tenant/site scoping and role-based permissions on integration APIs.
+
+## Detailed Behavior
+- Model behavior:
+  - `SiteIntegration`: site+account scoped; fields for platform, platform_type, config_json (content types, sync settings), credentials_json (API keys, etc.), active/sync flags, sync status, last_sync_at, sync_error; unique per site+platform.
+  - `SyncEvent`: per-integration/site event log with event_type/action, success flag, optional content_id/external_id, details JSON, error_message, duration, timestamps.
+  - `SiteIntegration.get_credentials` / `set_credentials` currently store JSON as-is (encryption to be added).
+- Service behavior (`IntegrationService`):
+  - `create_integration` sets account from site and saves config/credentials with platform/platform_type.
+  - `update_integration` updates config/credentials/is_active; `delete_integration` removes the record.
+  - `get_integration`/`list_integrations`/`get_integrations_for_site` fetch active integrations by site/platform.
+  - `test_connection` delegates to platform-specific testers (WordPress/Shopify implemented; others raise `NotImplementedError`).
+- API (`IntegrationViewSet`, router `/api/v1/integration/integrations/`):
+  - Inherits `SiteSectorModelViewSet` but overrides `get_queryset` to filter by site_id (no sector field).
+  - Permissions: `IsAuthenticatedAndActive` + `IsEditorOrAbove`; throttle scope `integration`.
+  - Serializer exposes derived `api_key` for WordPress; validates that WordPress integrations include an API key.
+  - Actions:
+    - `test_connection` (detail): calls `IntegrationService.test_connection` for the existing integration.
+    - `test_connection_collection` (AllowAny, no throttle): accepts site_id/api_key/site_url; validates site ownership or matching `Site.wp_api_key`; creates WordPress integration if missing, tests via `_test_wordpress_connection`, deletes if test fails, returns integration_id on success.
+    - `sync`: calls `SyncService.sync` (direction metadata/both/to_external/from_external); metadata-only uses `SyncMetadataService.sync_wordpress_structure`.
+    - `sync_status`: returns sync status via `SyncService.get_sync_status`.
+    - `update_site_structure`: updates `config_json.content_types` from WordPress push (post_types, taxonomies, plugin flags, timestamp).
+    - `get_content_types`: returns content type config.
+    - `debug_status`: uses `SyncHealthService` for debug data.
+    - `sync_wordpress_content`: calls `ContentSyncService.sync_from_wordpress` for a specific content_id.
+- Webhooks:
+  - Registered under `/api/v1/integration/webhooks/wordpress/status/` and `/metadata/` for incoming WordPress callbacks (handling in `webhooks.py`).
+
+## Data Structures / Models Involved (no code)
+- `SiteIntegration` config/credentials/sync flags/status/error.
+- `SyncEvent` event logs.
+- Site/account context from `auth.models.Site` and `Account`.
+
+## Execution Flow
+- CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls (integration/sync/health/content-sync) → model updates or sync actions.
+- Collection-level test may create integration, run test, and delete on failure.
+- Webhooks ingest external events; service handlers update integrations/sync events (implementation-specific).
+
+## Cross-Module Interactions
+- Integrations reference sites and are consumed by publishing/sync flows when pushing/pulling content.
+- WordPress API key path relies on `Site.wp_api_key` and integration credentials during connection tests.
+- Sync services interact with planner/writer content when syncing content or structure.
+
+## State Transitions
+- `SiteIntegration.sync_status/last_sync_at` update during sync; `is_active`/`sync_enabled` toggled via API.
+- `SyncEvent` records per-action success/failure with timestamps and optional IDs.
+
+## Error Handling
+- Unsupported platforms raise `NotImplementedError`; connection tests return structured success/message; newly created integrations are deleted if test fails in collection endpoint.
+- API returns 403/404/400 for invalid site/auth/API key; sync errors surface in responses and may populate `sync_error`.
+
+## Tenancy Rules
+- All integrations are site- and account-scoped; viewsets filter by site_id and require authenticated user with editor-or-above, or matching API key for collection-level WordPress test.
+
+## Billing Rules
+- None; integration operations do not alter credits.
+
+## Background Tasks / Schedulers
+- None dedicated; syncs run inline in service calls unless delegated inside sync services.
+
+## Key Design Considerations
+- Unique integration per site+platform avoids duplication.
+- Collection-level test supports plugin onboarding without prior authenticated session while still requiring site ownership or API key.
+- Credentials are currently stored plain JSON—add encryption before production use.
+
+## How Developers Should Work With This Module
+- Use `IntegrationService` for CRUD/test; avoid direct credential mutation outside service helpers.
+- Extend platform support by adding platform-specific test logic and serializer validation.
+- When adding new sync flows, use `SyncService`/`SyncMetadataService`/`ContentSyncService` and keep site/account scoping intact.
+

docs/90-ARCHIVED/master-docs-original/10-backend/planner/PLANNER-MODELS-AND-FLOW.md

@@ -0,0 +1,69 @@
+# Planner Models and Flow
+
+## Purpose
+Provide a detailed view of planner models, their constraints, and how planner CRUD/bulk operations move data toward the writer pipeline.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/planning/models.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- Services: `backend/igny8_core/business/planning/services/clustering_service.py`, `ideas_service.py`
+
+## High-Level Responsibilities
+- Maintain tenant/site/sector-scoped planner entities (Keywords, Clusters, ContentIdeas) backed by global SeedKeywords.
+- Enforce industry/sector alignment and uniqueness within site/sector.
+- Support search, filtering, ordering, and bulk operations for planner data.
+- Feed automation and writer tasks with curated ideas and clusters.
+
+## Detailed Behavior
+- Models:
+  - `Keywords`: links to `SeedKeyword`; overrides for volume/difficulty; optional cluster; status `new/mapped`; disabled flag; validation ensures seed keyword industry matches site industry and seed sector matches site sector’s industry sector; unique per site/sector and seed keyword; soft-delete enabled.
+  - `Clusters`: topic groups with counts, volume, mapped_pages, status `new/mapped`; unique per site/sector by name; soft-delete enabled.
+  - `ContentIdeas`: status `new/queued/completed`, content_type/structure choices, estimated word count, optional keyword objects M2M, keyword_cluster FK; soft-delete enabled.
+- Viewsets:
+  - `KeywordViewSet`: search by seed_keyword.keyword; filter by status, cluster, seed intent; ordering by created_at, seed volume/difficulty; custom range filters for difficulty/volume; requires site_id/sector_id on create; bulk_delete; two `bulk_update` actions (status); `bulk_add_from_seed` to create Keywords from SeedKeywords with site/sector validation.
+  - `ClusterViewSet`: site/sector filtered; CRUD; status updates; inherits filtering from base with developer/admin/system override.
+  - `ContentIdeasViewSet`: CRUD; filters by status/cluster; requires site_id/sector_id on create.
+- Serializers:
+  - `KeywordSerializer` demands `seed_keyword_id` on create; derives read-only keyword/volume/difficulty/intent from seed; supports volume/difficulty overrides; exposes cluster/sector names; write-only site_id/sector_id.
+  - `ClusterSerializer` exposes sector name; write-only site_id/sector_id; counts/volume/mapped_pages read-only.
+  - `ContentIdeasSerializer` exposes cluster/sector names; write-only site_id/sector_id.
+- Services:
+  - `ClusteringService` and `IdeasService` (not expanded here) are used by automation/AI flows for clustering and idea generation.
+
+## Execution Flow
+- Planner CRUD/bulk requests → DRF auth → `SiteSectorModelViewSet` filtering → serializer validation (seed/site/sector) → model save → unified response.
+- Bulk operations act on the filtered queryset (account/site/sector scoped).
+- Automation stages 1–3 consume planner data and advance statuses.
+
+## Cross-Module Interactions
+- Writer tasks and content reference clusters/ideas; automation transforms planner data into tasks/content/images.
+- Billing credit checks occur in automation/AI calls that process planner entities.
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+- Disabled flag excludes records from automation queries.
+
+## Error Handling
+- Validation errors for missing site/sector or seed keyword; industry/sector mismatch raises validation errors in `Keywords`.
+- Bulk operations return 400 when IDs/status missing; generic errors return unified 500 responses.
+
+## Tenancy Rules
+- All planner models inherit tenant/site/sector fields; base viewsets filter accordingly. Admin/developer/system accounts can bypass filtering; persisted data retains tenant/site/sector ownership.
+- Create paths require explicit site/sector; account set from site/user/middleware.
+
+## Billing Rules
+- Planner endpoints do not directly deduct credits; AI-based clustering/idea generation uses billing when invoked via services/automation.
+
+## Background Tasks / Schedulers
+- None in planner endpoints; automation runs stages asynchronously using planner data.
+
+## Key Design Considerations
+- Strict site/sector + seed alignment prevents cross-site contamination.
+- Read-only seed-derived fields avoid drift while allowing per-site overrides.
+- Bulk endpoints and range filters support large keyword sets efficiently.
+
+## How Developers Should Work With This Module
+- Use existing serializers/viewsets to add fields or validations; keep site/sector required on create.
+- When adding AI-powered planner actions, ensure credit checks go through billing services and queries respect tenant/site/sector scoping.
+- Clean up duplicate `bulk_update` definitions if extending bulk behaviors to avoid route collisions.

docs/90-ARCHIVED/master-docs-original/10-backend/planner/PLANNER-OVERVIEW.md

@@ -0,0 +1,80 @@
+# Planner Overview
+
+## Purpose
+Explain how the planner module manages keywords, clusters, and content ideas, including tenancy, validation, and API behaviors.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/planning/models.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- URLs: `backend/igny8_core/modules/planner/urls.py`
+- Services: `backend/igny8_core/business/planning/services/clustering_service.py`, `ideas_service.py`
+
+## High-Level Responsibilities
+- Store site/sector-scoped keywords, clusters, and content ideas linked to global seed keywords.
+- Provide CRUD and bulk operations for keywords/clusters/ideas with search, filter, and ordering.
+- Validate industry/sector alignment between seed keywords and site/sector.
+- Feed downstream writer/automation stages with structured ideas and clusters.
+
+## Detailed Behavior
+- Models (site/sector scoped via `SiteSectorBaseModel` and soft-delete):
+  - `Keywords`: references global `SeedKeyword`; optional volume/difficulty overrides; optional cluster; status `new/mapped`; disabled flag; validation ensures seed keyword industry/sector match the site/sector.
+  - `Clusters`: topic groups with counts, volume, mapped_pages, status `new/mapped`; unique per site/sector by name.
+  - `ContentIdeas`: ideas tied to clusters and optional keyword objects; status `new/queued/completed`; content_type/structure and estimated_word_count; disabled flag.
+- Serializers:
+  - `KeywordSerializer` enforces `seed_keyword_id` on create; exposes seed keyword-derived fields (keyword/volume/difficulty/intent) read-only; optional overrides; includes site_id/sector_id write-only; provides cluster/sector names via getters; optional `attribute_values` when `USE_SITE_BUILDER_REFACTOR` flag is enabled.
+  - `ClusterSerializer` exposes site/sector IDs, sector name, read-only counts/volume/mapped_pages.
+  - `ContentIdeasSerializer` exposes cluster/sector names, content type/structure, keyword/target fields, site/sector write-only.
+- Views (`KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet`):
+  - Inherit `SiteSectorModelViewSet` for tenant/site/sector filtering and unified responses.
+  - Permissions: `IsAuthenticatedAndActive` + viewer-or-above (search/list CRUD).
+  - Pagination: `CustomPageNumberPagination`; throttle scope `planner`.
+  - Filters/Search/Ordering: keywords searchable by seed_keyword.keyword; filter by status, cluster_id, seed intent; ordering by created_at, volume, difficulty; custom range filters for difficulty/volume; clusters filter by status; ideas filter by status/cluster.
+  - Creation requires explicit `site_id` and `sector_id`; viewsets validate site/sector existence and alignment; set `account/site/sector` explicitly on save.
+  - Bulk endpoints:
+    - Keywords: `bulk_delete`, two definitions of `bulk_update` (status update) present; `bulk_add_from_seed` to create Keywords from SeedKeywords with site/sector validation.
+    - Clusters: bulk update endpoints in view (not shown above) adjust status.
+    - Ideas: creation and status updates follow standard CRUD; not shown as bulk endpoints in code snippet.
+  - Error handling: viewsets wrap errors into unified responses; return 400/404/500 as appropriate.
+- Services:
+  - `ClusteringService` and `IdeasService` (not detailed here) provide additional business logic for clustering/idea generation when invoked by automation or endpoints.
+
+## Data Structures / Models Involved (no code)
+- `Keywords`, `Clusters`, `ContentIdeas`; global `SeedKeyword`.
+- Tenancy entities: `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → `SiteSectorModelViewSet` filters by account/site/sector → serializers validate seed/site/sector alignment → models persisted → responses returned via unified helpers; bulk actions operate on filtered querysets.
+
+## Cross-Module Interactions
+- Automation stages 1–3 consume planner data (keywords → clusters → ideas → tasks).
+- Writer tasks reference clusters/ideas produced here.
+- Billing credits may be checked upstream for AI clustering/idea generation (via services invoked in automation or planner actions).
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+- Disabled flag can exclude records from processes.
+
+## Error Handling
+- Validation enforces seed/site/sector industry alignment; missing site/sector on create raises validation errors.
+- Bulk operations return 400 on missing IDs/status; general errors return unified 500 responses.
+
+## Tenancy Rules
+- All planner models inherit `SiteSectorBaseModel`; queries are filtered by account/site/sector; admin/developer/system roles can bypass filtering via base viewset logic.
+- Create requires explicit site and sector; viewsets fetch and set account from site/user/middleware.
+
+## Billing Rules
+- None directly in the planner endpoints; credit costs for clustering/idea generation are enforced where those services are called (automation or planner service usage).
+
+## Background Tasks / Schedulers
+- Planner endpoints run synchronously; automation may batch planner data into AI tasks via Celery (documented in automation).
+
+## Key Design Considerations
+- Strict site/sector validation prevents cross-tenant or cross-site leaks.
+- Seed keyword linkage centralizes keyword metadata; overrides allow per-site tuning.
+- Pagination/filtering/search are optimized for large keyword sets.
+
+## How Developers Should Work With This Module
+- Use provided viewsets and serializers; ensure site_id/sector_id are supplied on create.
+- When adding fields, extend serializers with read-only/write-only behavior consistent with current patterns.
+- For new bulk operations, follow existing patterns: validate IDs, operate on filtered queryset, return unified responses.

docs/90-ARCHIVED/master-docs-original/10-backend/writer/WRITER-OVERVIEW.md

@@ -0,0 +1,82 @@
+# Writer Overview
+
+## Purpose
+Describe how the writer module manages tasks, content, images, and taxonomies, including validations, tenancy, and API behaviors.
+
+## Code Locations (exact paths)
+- Models: `backend/igny8_core/business/content/models.py`
+- Serializers: `backend/igny8_core/modules/writer/serializers.py`
+- Views: `backend/igny8_core/modules/writer/views.py`
+- URLs: `backend/igny8_core/modules/writer/urls.py`
+- Services: `backend/igny8_core/business/content/services/content_generation_service.py`, `validation_service.py`, `metadata_mapping_service.py`
+- Automation linkages: `backend/igny8_core/business/automation/services/automation_service.py` (stages 3–6)
+
+## High-Level Responsibilities
+- Manage tenant/site/sector-scoped tasks, generated/imported content, images, and taxonomies.
+- Provide CRUD and bulk operations for tasks and images; content generation triggers; taxonomy CRUD.
+- Enforce site/sector alignment on creation and propagate account/site/sector to related records.
+- Feed automation and publishing flows with content and images, and integrate with billing credits for AI operations.
+
+## Detailed Behavior
+- Models (all inherit tenant/site/sector bases; many soft-deletable):
+  - `Tasks`: queued work items tied to clusters/ideas/taxonomy; content type/structure; keywords text; word_count target; status `queued/completed`.
+  - `Content`: generated/imported content with HTML, SEO fields, cluster link, content type/structure, taxonomy M2M, external IDs/URLs/metadata, sync status, source (`igny8/wordpress`), status (`draft/review/published`), word_count, timestamps.
+  - `Images`: linked to content or task; auto-sets account/site/sector from provider; tracks type, URL/path, prompt, status, position.
+  - `ContentTaxonomy`: site/sector taxonomy terms (category/tag) with external taxonomy/id, sync status, description, count, metadata; unique per site by slug+type and by external id+taxonomy.
+  - Supporting: `ContentClusterMap`, `ContentAttribute` (documented in domain models).
+- Serializers:
+  - `TasksSerializer`: requires cluster/content_type/content_structure on create; exposes cluster/sector names; write-only site_id/sector_id; defaults status to queued if absent.
+  - `ImagesSerializer`: exposes task/content titles; read-only derived fields; creation requires site/sector (validated, with fallback to request user active site default sector); sets account/site/sector via base perform_create.
+  - `ContentSerializer`: exposes cluster/sector names; taxonomy terms grouped (tags/categories); image status flags; write-only site_id/sector_id; validates presence of required fields and status transitions.
+  - Group serializers for images support grouped responses by content.
+- Views:
+  - `TasksViewSet`: filters/search/order; bulk_delete, bulk_update status; `auto_generate_content` triggers `ContentGenerationService.generate_content` for up to 10 tasks, enforcing account presence and credit checks (returns 402 on `InsufficientCreditsError`); inherits tenant/site/sector filtering.
+  - `ImagesViewSet`: CRUD with ordering/filtering; perform_create enforces site/sector and populates context; `serve_image_file` serves local files with basic checks.
+  - `ContentViewSet`: CRUD for content; ordering/filtering; handles taxonomy assignments; exposes status/SEO fields; uses base scoping.
+  - `ContentTaxonomyViewSet`: CRUD for taxonomy terms (category/tag) scoped to site/sector; inherits base scoping.
+- Services:
+  - `ContentGenerationService`: invoked by `auto_generate_content`; orchestrates AI content generation for tasks, returns async task_id when queued or synchronous result; raises `InsufficientCreditsError` on low balance.
+  - `ContentValidationService`, `MetadataMappingService`: additional processing/validation/mapping (used in writer flows and publishing).
+- Automation linkage:
+  - Stage 3 creates tasks from ideas; Stage 4 generates content; Stage 5 generates image prompts; Stage 6 generates images and moves content to review.
+
+## Data Structures / Models Involved (no code)
+- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, plus `ContentClusterMap`/`ContentAttribute`.
+- Tenancy entities: `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → `SiteSectorModelViewSet` filtering → serializer validation (site/sector required on create) → model save → unified response.
+- `auto_generate_content` validates task IDs/account, calls service → service may enqueue Celery AI tasks or run synchronously → response with task_id or result.
+- Images creation auto-inherits account/site/sector from linked task/content; local file serving bypasses account filter for read-only access.
+
+## Cross-Module Interactions
+- Planner clusters/ideas feed tasks; tasks/content/images feed publishing and automation stages.
+- Billing credits enforced via `ContentGenerationService` when AI is used; automation aggregates credits used per stage from AI task logs.
+- Integration/publishing sync uses content/taxonomy/image data when pushing to external platforms.
+
+## State Transitions
+- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`; Taxonomies created/updated/deleted via CRUD.
+
+## Error Handling
+- Viewsets return unified errors; bulk operations validate IDs/status; `auto_generate_content` returns 400/404/402/500 depending on validation, missing tasks, insufficient credits, or unexpected errors.
+- Images file serving returns 404 on missing file/image.
+
+## Tenancy Rules
+- Base viewset filters enforce account/site/sector scoping; admins/developers/system can bypass filtering; persisted records retain tenant/site/sector ownership.
+- Creation requires site/sector; account set from request/site/user; Images perform_create validates presence of site/sector.
+
+## Billing Rules
+- AI content generation is guarded by credit checks; InsufficientCredits returns HTTP 402; credit logging occurs in billing services at AI call sites.
+
+## Background Tasks / Schedulers
+- AI generation may run via Celery when `ContentGenerationService` returns a task_id; automation stages run inside Celery workers for bulk flows.
+
+## Key Design Considerations
+- Strict site/sector requirements prevent cross-site contamination.
+- Bulk limits (max 10 tasks in auto_generate_content) to control credit burn and processing load.
+- Image serving permits public access via endpoint while still performing existence checks.
+
+## How Developers Should Work With This Module
+- Use existing serializers/viewsets; keep site/sector required on create.
+- When extending AI generation, ensure billing checks (`CreditService`) and account/site scoping are preserved.
+- For new bulk actions, follow current patterns: validate input, operate on filtered queryset, return unified responses.

docs/90-ARCHIVED/master-docs-original/20-api/API-OVERVIEW.md

@@ -0,0 +1,79 @@
+# API Overview
+
+## Purpose
+Describe the overall API surface, routing, authentication, pagination, throttling, and response format implemented in the backend.
+
+## Code Locations (exact paths)
+- Root routing: `backend/igny8_core/urls.py`
+- Module routers:
+  - Auth: `backend/igny8_core/auth/urls.py`
+  - Account management: `backend/igny8_core/api/urls.py`
+  - Planner: `backend/igny8_core/modules/planner/urls.py`
+  - Writer: `backend/igny8_core/modules/writer/urls.py`
+  - System: `backend/igny8_core/modules/system/urls.py`
+  - Billing (full): `backend/igny8_core/business/billing/urls.py`
+  - Billing admin: `backend/igny8_core/modules/billing/admin_urls.py`
+  - Automation: `backend/igny8_core/business/automation/urls.py`
+  - Linker: `backend/igny8_core/modules/linker/urls.py`
+  - Optimizer: `backend/igny8_core/modules/optimizer/urls.py`
+  - Publisher: `backend/igny8_core/modules/publisher/urls.py`
+  - Integration: `backend/igny8_core/modules/integration/urls.py`
+- DRF settings: `backend/igny8_core/settings.py` (REST_FRAMEWORK config)
+- Base viewsets/responses: `backend/igny8_core/api/base.py`, `backend/igny8_core/api/response.py`
+
+## High-Level Responsibilities
+- Expose REST endpoints under `/api/v1/*` for auth, account/team, planner, writer, system, billing, automation, linker, optimizer, publisher, and integration.
+- Enforce unified response format, tenant scoping, authentication (API key/JWT/session/basic), and scoped throttling.
+- Provide OpenAPI schema and interactive docs at `/api/schema`, `/api/docs`, `/api/redoc`.
+
+## Detailed Behavior
+- Routing (root): `/api/v1/auth/`, `/api/v1/account/`, `/api/v1/planner/`, `/api/v1/writer/`, `/api/v1/system/`, `/api/v1/billing/`, `/api/v1/admin/` (billing admin), `/api/v1/automation/`, `/api/v1/linker/`, `/api/v1/optimizer/`, `/api/v1/publisher/`, `/api/v1/integration/`. Admin + CSV helpers mounted under `/admin/`.
+- Auth stack (settings REST_FRAMEWORK):
+  - `APIKeyAuthentication` (WordPress bridge, sets request.account/site when Bearer token is not JWT-like).
+  - `JWTAuthentication` (Bearer JWT access tokens).
+  - `CSRFExemptSessionAuthentication` (session without CSRF for API).
+  - Basic auth fallback.
+- Permissions default AllowAny in settings; individual viewsets specify stricter permissions (e.g., `IsAuthenticatedAndActive`, role checks).
+- Tenancy: `AccountContextMiddleware` sets `request.account`; base viewsets (`AccountModelViewSet`, `SiteSectorModelViewSet`) auto-filter querysets by account/site/sector and set account on create.
+- Pagination: `CustomPageNumberPagination` (page/ page_size; defaults in settings).
+- Filtering/search/ordering: enabled globally via DRF filter backends; viewsets declare fields and search options.
+- Throttling: `DebugScopedRateThrottle` with scope keys defined in settings for auth, planner, writer, billing, automation, etc.; bypassed when `IGNY8_DEBUG_THROTTLE` true.
+- Responses: success/error helpers wrap payloads with `success`, `data`/`error`, optional `errors`, and `request_id`.
+- OpenAPI: drf-spectacular configured with tags, schema routes; interactive docs at `/api/docs` (Swagger UI) and `/api/redoc`.
+
+## Data Structures / Models Involved (no code)
+- See module-specific docs; API layer uses serializers tied to planner/writer/billing/auth/etc. models.
+
+## Execution Flow
+- Request → middleware (request ID, account context, resource tracking) → DRF auth (API key/JWT/session) → viewset/action → serializer validation → model ops → unified response. Pagination/filtering/search applied where configured.
+
+## Cross-Module Interactions
+- Auth endpoints issue JWTs consumed by all other modules.
+- Tenancy middleware/context is shared across all module viewsets.
+- Billing credits enforced in content/automation flows via service calls, surfaced through billing endpoints.
+
+## State Transitions
+- Handled in module viewsets (e.g., task status changes, run statuses); API layer mediates CRUD and custom actions.
+
+## Error Handling
+- Custom exception handler (enabled by default) wraps errors in unified format.
+- Viewsets return structured 400/401/403/404/500 responses; throttling returns standard DRF throttle responses.
+
+## Tenancy Rules
+- Account/site/sector scoping enforced by middleware + base viewsets; admin/developer/system roles may bypass filters at the viewset layer per role helpers.
+
+## Billing Rules
+- Credit checks occur in service calls (content generation, automation); billing endpoints report balances/usage/limits. Some endpoints return 402 on insufficient credits.
+
+## Background Tasks / Schedulers
+- Automation and some AI flows run via Celery; API endpoints trigger tasks (e.g., automation run_now, writer auto_generate_content).
+
+## Key Design Considerations
+- Consistent routing under `/api/v1/` with module-specific routers.
+- Unified responses and throttling scopes to keep client behavior consistent.
+- OpenAPI docs generated from viewset/serializer annotations for discoverability.
+
+## How Developers Should Work With This Module
+- Mount new modules under `/api/v1/<module>/` in `igny8_core/urls.py`.
+- Inherit from base viewsets to get scoping/unified responses; declare permissions, filters, and throttles per viewset.
+- Annotate endpoints with drf-spectacular for accurate schema; keep success/error responses consistent via helpers.

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/accounts.md

@@ -0,0 +1,56 @@
+# Account Endpoints
+
+## Purpose
+Document account management endpoints for settings, team management, and usage analytics.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/api/urls.py`
+- Views: `backend/igny8_core/api/account_views.py`
+- Settings/tenancy middleware: `backend/igny8_core/auth/middleware.py`
+
+## High-Level Responsibilities
+- Provide account settings retrieval/update, team member management, and usage analytics summaries for the authenticated account.
+
+## Detailed Behavior
+- Base path: `/api/v1/account/`
+- Settings:
+  - `GET /api/v1/account/settings/` → returns account settings (ViewSet `retrieve`).
+  - `PATCH /api/v1/account/settings/` → partial update of account settings.
+- Team:
+  - `GET /api/v1/account/team/` → list team members.
+  - `POST /api/v1/account/team/` → create/add a team member.
+  - `DELETE /api/v1/account/team/<id>/` → remove a team member.
+- Usage analytics:
+  - `GET /api/v1/account/usage/analytics/` → returns usage analytics overview (implementation in `UsageAnalyticsViewSet.overview`).
+- Permissions/tenancy: views expect authenticated users; account context from middleware; data scoped to `request.account`.
+
+## Data Structures / Models Involved (no code)
+- Account, User, and related analytics data as computed in account views.
+
+## Execution Flow
+- Requests hit `account_views` ViewSets; account context derived from session/JWT via middleware; view methods return unified responses.
+
+## Cross-Module Interactions
+- Usage analytics may summarize module usage (planner/writer/etc.) depending on `UsageAnalyticsViewSet` implementation.
+
+## State Transitions
+- Account settings updates; team membership changes.
+
+## Error Handling
+- Standard unified responses for validation/auth errors; 404 when deleting non-existent team members.
+
+## Tenancy Rules
+- All endpoints scoped to authenticated user’s account; no cross-tenant access.
+
+## Billing Rules
+- None directly; account limits and credits are exposed via billing endpoints.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- Non-router endpoints used for simplicity; still leverage DRF ViewSet actions.
+
+## How Developers Should Work With This Module
+- Keep settings/team/usage endpoints under `/api/v1/account/`; ensure account context is required for all operations.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/authentication.md

@@ -0,0 +1,62 @@
+# Authentication Endpoints
+
+## Purpose
+Detail authentication-related endpoints for registration, login, password change, token refresh, and auth-adjacent resources (users/accounts/plans/sites/sectors/industries/seed keywords).
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/auth/urls.py`
+- Views: `backend/igny8_core/auth/views.py`
+- Serializers: `backend/igny8_core/auth/serializers.py`
+- Auth utils: `backend/igny8_core/auth/utils.py`
+
+## High-Level Responsibilities
+- Issue JWT access/refresh tokens and session auth on login.
+- Register users, change passwords, refresh tokens.
+- Provide CRUD for users, accounts, subscriptions, site access, plans, sites, sectors, industries, seed keywords via routers.
+
+## Detailed Behavior
+- APIViews:
+  - `POST /api/v1/auth/register/` → `RegisterView`: validates via `RegisterSerializer`, creates user, returns user data.
+  - `POST /api/v1/auth/login/` → `LoginView`: validates credentials, logs in user (session), generates access/refresh JWTs with expiries, returns user data and tokens; 401 on invalid credentials.
+  - `POST /api/v1/auth/change-password/` → `ChangePasswordView`: requires auth, validates old/new passwords, updates password; 400 on invalid current password or validation errors.
+  - `POST /api/v1/auth/refresh/` → `RefreshTokenView`: accepts refresh token, validates, issues new access token with expiry; 401/400 on invalid/expired tokens.
+- Routers under `/api/v1/auth/`:
+  - `groups/`, `users/`, `accounts/`, `subscriptions/`, `site-access/`, `plans/`, `sites/`, `sectors/`, `industries/`, `seed-keywords/` mapped to corresponding viewsets in `auth/views.py`. These use base viewsets with tenant filtering and role checks (see module docs).
+- CSV admin helpers (admin UI, not public API): CSV import/export for industry/industrysector/seedkeyword under `/admin/igny8_core_auth/...`.
+
+## Data Structures / Models Involved (no code)
+- `User`, `Account`, `Plan`, `Site`, `Sector`, `Industry`, `SeedKeyword`, `Subscription`, `SiteUserAccess`, `Group`.
+
+## Execution Flow
+- APIView endpoints use serializers to validate, then issue tokens via auth utils (JWT encode with user_id/account_id, type, exp).
+- Router endpoints inherit base viewsets; AccountContextMiddleware sets `request.account`; JWT/Session auth applied per settings; permissions enforced per viewset.
+
+## Cross-Module Interactions
+- Tokens issued here are required by planner/writer/billing/automation/etc.
+- Account/plan/site data informs tenancy and plan enforcement in middleware and billing limits.
+
+## State Transitions
+- User creation, password changes, session login, token issuance/refresh.
+- CRUD on accounts/sites/sectors/industries/seed keywords via routers.
+
+## Error Handling
+- Unified error responses via helpers; login returns 401 on invalid credentials; refresh returns 401/400 on invalid/expired tokens; validation errors return 400 with field errors.
+
+## Tenancy Rules
+- Login loads user with account+plan; middleware later enforces active plan. Router viewsets inherit account/site/sector filtering where applicable.
+
+## Billing Rules
+- None directly; plan data carried on Account; credits handled elsewhere.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- JWT payload includes user_id, account_id, type, exp/iat; uses `JWT_SECRET_KEY`/`JWT_ALGORITHM` from settings.
+- Session login occurs alongside JWT issuance to support browser-based flows.
+
+## How Developers Should Work With This Module
+- Use provided APIViews for auth; do not handcraft JWTs—use `generate_access_token`/`generate_refresh_token`.
+- When extending auth resources (e.g., new user fields), update serializers and viewsets; keep router paths stable.
+- Maintain unified responses and permission/tenancy checks in viewsets.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/automation.md

@@ -0,0 +1,65 @@
+# Automation Endpoints
+
+## Purpose
+Describe automation API endpoints that configure, trigger, monitor, and control automation runs.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/automation/urls.py`
+- Views: `backend/igny8_core/business/automation/views.py`
+- Services/Tasks: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`, `backend/igny8_core/business/automation/tasks.py`
+
+## High-Level Responsibilities
+- Expose configuration CRUD (get/update) and operational controls (run, pause, resume, cancel).
+- Provide run history, status, logs, pipeline overview, credit estimate, and current processing state.
+- Enforce site/account scoping and authentication.
+
+## Detailed Behavior
+- Base path: `/api/v1/automation/`
+- Key endpoints (actions on `AutomationViewSet`):
+  - `GET config?site_id=` → get/create `AutomationConfig` for site (includes batch sizes, delays, schedule, flags, last/next run).
+  - `PUT update_config?site_id=` → update config fields (enable, frequency, scheduled_time, batch sizes, delays).
+  - `POST run_now?site_id=` → start a run (checks locks/credits) and enqueue Celery `run_automation_task`.
+  - `GET current_run?site_id=` → current running/paused run details with per-stage results and totals.
+  - `GET history?site_id=` → last 20 runs with status and timestamps.
+  - `GET logs?run_id=&lines=` → tail of automation log file for run.
+  - `GET estimate?site_id=` → estimated credits required plus current balance and sufficiency flag (1.2× buffer).
+  - `GET pipeline_overview?site_id=` → counts/pending by stage across planner/writer models.
+  - `GET current_processing?site_id=&run_id=` → live processing state for active run.
+  - `POST pause?run_id=` / `POST resume?run_id=` / `POST cancel?run_id=` → control run state (pause/resume/cancel).
+- Permissions/tenancy: `IsAuthenticated`; site fetched with `account=request.user.account`; automation lock is per site; `request.account` set by middleware.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`, `AutomationRun`, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images).
+
+## Execution Flow
+- View actions call `AutomationService` to start/control runs; long-running work executed by Celery tasks (`run_automation_task`, `resume_automation_task`).
+- Config updates persist to DB; run state and logs updated as stages progress.
+
+## Cross-Module Interactions
+- Uses planner/writer data for counts and processing; AI functions run inside service; billing credits checked via account balance before start and inferred from AI task logs during execution.
+
+## State Transitions
+- Run status: running ↔ paused → completed/failed/cancelled; `current_stage` advances per stage; per-stage results stored in `AutomationRun`.
+- Config `last_run_at`/`next_run_at` updated on scheduled runs.
+
+## Error Handling
+- Missing site_id/run_id → 400; run not found → 404; insufficient credits or concurrent run → 400; server errors → 500.
+- Logs endpoint 404s when run missing.
+
+## Tenancy Rules
+- All operations scoped to the authenticated user’s account/site; no cross-tenant access; locks are per site.
+
+## Billing Rules
+- Start requires credits ≥ estimated * 1.2; credits consumed by AI tasks are recorded via AI task logs and aggregated per stage.
+
+## Background Tasks / Schedulers
+- Celery tasks for scheduled runs (`check_scheduled_automations`) and pipeline execution/resume.
+
+## Key Design Considerations
+- Cooperative pause/resume/cancel with persisted partial results.
+- Log access via filesystem tail; structured per-stage results stored in DB for quick status reads.
+
+## How Developers Should Work With This Module
+- Trigger runs via `run_now`; avoid bypassing locks/credit checks.
+- Extend actions by reusing `AutomationService` and Celery tasks; keep site scoping and error handling consistent.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/billing.md

@@ -0,0 +1,77 @@
+# Billing Endpoints
+
+## Purpose
+Detail billing API endpoints for invoices, payments, credit packages, transactions, payment methods, and credit balance/usage.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Views: `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/modules/billing/views.py`
+- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+
+## High-Level Responsibilities
+- Expose billing resources (invoices, payments, credit packages, payment methods, credit transactions).
+- Provide credit balance/usage/limits endpoints.
+- Support manual payment submission and available payment methods lookup.
+
+## Detailed Behavior
+- Base paths:
+  - `/api/v1/billing/` (business billing views via router)
+  - `/api/v1/admin/` (admin billing URLs)
+  - `/api/v1/billing/credits/...` (balance/usage/transactions aliases)
+- Invoice endpoints (`InvoiceViewSet`):
+  - `GET /invoices/` list account invoices (status filter optional).
+  - `GET /invoices/{id}/` invoice detail.
+  - `GET /invoices/{id}/download_pdf/` returns PDF bytes (placeholder).
+- Payment endpoints (`PaymentViewSet`):
+  - `GET /payments/` list payments (status filter optional).
+  - `GET /payment-methods/available/` returns available methods (country/config driven).
+  - `POST /payments/manual/` submit manual payment for an invoice (requires invoice_id, payment_method, transaction_reference; rejects already paid).
+- Account payment methods (`AccountPaymentMethodViewSet`):
+  - CRUD at `/payment-methods/`; `POST /payment-methods/{id}/set_default/` toggles default for the account.
+- Credit packages (`CreditPackageViewSet`):
+  - `GET /credit-packages/` list active packages.
+  - `POST /credit-packages/{id}/purchase/` creates invoice and returns next_action (Stripe/PayPal placeholders; manual fallback returns invoice info).
+- Credit transactions (`CreditTransactionViewSet`):
+  - `GET /transactions/` ledger of credit changes; also registered under `/credits/transactions/`.
+- Credit balance/usage/limits (`modules/billing/views.py`):
+  - `GET /credits/balance/` returns credits, plan monthly credits, month-to-date credits used.
+  - `GET /credits/usage/` returns paginated usage logs with filters; `GET /credits/usage/summary/` aggregates by operation/model and totals; `GET /credits/usage/limits/` returns plan/account limits and usage counts.
+- Permissions/tenancy: authenticated users; account-scoped querysets; viewsets rely on `request.account` or `request.user.account`.
+
+## Data Structures / Models Involved (no code)
+- `Invoice`, `Payment`, `CreditPackage`, `CreditTransaction`, `AccountPaymentMethod`, `PaymentMethodConfig`, `CreditUsageLog`, `CreditCostConfig`, `Account`, `Plan`.
+
+## Execution Flow
+- Router dispatch → viewset → service calls (invoice/payment/credit) → DB updates → unified responses. Balance/usage endpoints compute aggregates on demand.
+
+## Cross-Module Interactions
+- Credit costs/checks used by writer/automation AI flows; balances/usage reflect those deductions.
+- Plan limits surfaced in limits endpoint relate to account management in auth/account domains.
+
+## State Transitions
+- Invoices: draft/pending/paid/void/uncollectible; Payments: pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled; Credits balance changes via transactions.
+
+## Error Handling
+- Manual payment: 400 on missing fields or already-paid invoice.
+- Credit operations: 402 returned by upstream callers on `InsufficientCreditsError`.
+- Balance/usage: returns zeros/empty when account/plan missing.
+
+## Tenancy Rules
+- All billing data filtered by account; no cross-tenant access. Default viewsets inherit account scoping from base classes.
+
+## Billing Rules
+- Credit costs come from `CreditCostConfig` or constants; deductions recorded in ledger + usage logs.
+- Available methods and packages are filtered by active flags/config.
+
+## Background Tasks / Schedulers
+- None specific; Stripe/PayPal integrations are placeholders; any future webhooks should update invoices/payments/credits accordingly.
+
+## Key Design Considerations
+- Ledger + usage logs kept in sync via `CreditService`.
+- Manual payment flow avoids storing sensitive data; account payment methods store metadata only.
+
+## How Developers Should Work With This Module
+- Use `CreditService` for credit math; do not mutate balances directly.
+- Implement Stripe/PayPal flows in `PaymentService` if adding gateways; wire webhooks to update models.
+- Keep account scoping on all queries; reuse existing viewsets for new billing features.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/integration.md

@@ -0,0 +1,66 @@
+# Integration Endpoints
+
+## Purpose
+Document integration API endpoints for managing site integrations, testing connections, syncing, and handling WordPress webhooks.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/integration/urls.py`
+- Views: `backend/igny8_core/modules/integration/views.py`
+- Webhooks: `backend/igny8_core/modules/integration/webhooks.py`
+- Services: `backend/igny8_core/business/integration/services/*`
+
+## High-Level Responsibilities
+- CRUD for `SiteIntegration` records.
+- Test connections (detail and collection-level), trigger syncs, fetch sync status, update site structure, and sync WordPress content.
+- Expose WordPress webhook endpoints for status/metadata updates.
+
+## Detailed Behavior
+- Base path: `/api/v1/integration/`
+- Viewset: `IntegrationViewSet` (`/integrations/`, inherits `SiteSectorModelViewSet` but overrides queryset to filter by site_id since integrations have site only).
+  - Permissions: `IsAuthenticatedAndActive`, `IsEditorOrAbove`; throttle scope `integration`.
+  - Serializer exposes derived `api_key` (from credentials) and validates WordPress integrations require API key.
+  - Actions:
+    - `test_connection` (detail): calls `IntegrationService.test_connection` on existing integration; returns success/error.
+    - `test_connection_collection` (POST `integrations/test-connection/`, AllowAny): accepts site_id/api_key/site_url; validates site ownership or matching `Site.wp_api_key`; creates integration if missing; tests WordPress connection; deletes integration on failure; returns integration_id on success.
+    - `sync`: triggers `SyncService.sync` (direction metadata/both/to_external/from_external); metadata-only path uses `SyncMetadataService` internally.
+    - `sync_status`: returns sync status from `SyncService`.
+    - `update_site_structure`: updates `config_json.content_types` (post_types/taxonomies, plugin flags, timestamp) from WordPress push payload.
+    - `get_content_types`: returns content type config from integration config.
+    - `debug_status`: returns debug data via `SyncHealthService`.
+    - `sync_wordpress_content`: calls `ContentSyncService.sync_from_wordpress` for a specific content_id.
+- Webhooks:
+  - `/webhooks/wordpress/status/` and `/webhooks/wordpress/metadata/` endpoints for WordPress callbacks (handled in `webhooks.py`).
+
+## Data Structures / Models Involved (no code)
+- `SiteIntegration`, `SyncEvent`, `Site`, `Account`.
+
+## Execution Flow
+- CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls → model updates/sync actions. Collection-level test may create/delete integration based on result. Webhooks call handlers for incoming WordPress events.
+
+## Cross-Module Interactions
+- Integrations used by publishing/sync flows to external platforms; WordPress API key path relies on `Site.wp_api_key` and integration credentials.
+- Sync services interact with writer/planner content for metadata/content sync.
+
+## State Transitions
+- Integration `sync_status/last_sync_at/is_active/sync_enabled` updated by sync/test actions; `SyncEvent` records per-action success/failure with timestamps and IDs.
+
+## Error Handling
+- Invalid site/auth/API key return 403/404/400; unsupported platforms raise `NotImplementedError`; failed collection-level tests delete newly created integrations.
+
+## Tenancy Rules
+- All endpoints scoped to the site/account; queryset filters by site_id and permissions enforce authenticated editor-or-above unless using collection-level API key path.
+
+## Billing Rules
+- None; integration endpoints do not change credits.
+
+## Background Tasks / Schedulers
+- None specific; sync logic executes in service calls (may delegate internally).
+
+## Key Design Considerations
+- Single integration per site+platform; collection-level test supports plugin onboarding with API key.
+- Credentials stored as JSON (encryption pending).
+
+## How Developers Should Work With This Module
+- Use `IntegrationService` for CRUD/test; extend platform support via new test logic and serializer validation.
+- Keep site scoping and API key validation intact for collection-level tests.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/linker.md

@@ -0,0 +1,48 @@
+# Linker Endpoints
+
+## Purpose
+Document linker API endpoints for internal linking operations.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/linker/urls.py`
+- Views: `backend/igny8_core/modules/linker/views.py`
+- Services: `backend/igny8_core/business/linking/services/*`
+
+## High-Level Responsibilities
+- Provide linker-related endpoints (as defined in `LinkerViewSet`) for managing internal linking logic.
+
+## Detailed Behavior
+- Base path: `/api/v1/linker/`
+- Router registers root `LinkerViewSet` (see module code for actions/fields).
+- Inherits base viewset scoping, unified responses, permissions, throttling defined in module views.
+
+## Data Structures / Models Involved (no code)
+- Linking-related models/services (see business/linking).
+
+## Execution Flow
+- Requests → DRF auth → LinkerViewSet → service logic → unified response.
+
+## Cross-Module Interactions
+- May consume writer content to generate linking recommendations; interacts with linker services.
+
+## State Transitions
+- As defined by LinkerViewSet actions (not detailed in code snippet).
+
+## Error Handling
+- Standard unified responses and throttling.
+
+## Tenancy Rules
+- Inherits account/site scoping from base classes.
+
+## Billing Rules
+- None specified.
+
+## Background Tasks / Schedulers
+- None specified in endpoints.
+
+## Key Design Considerations
+- Endpoint actions rely on business/linking services; keep scoping intact.
+
+## How Developers Should Work With This Module
+- Extend LinkerViewSet/actions as needed; ensure base scoping and unified responses remain consistent.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/optimizer.md

@@ -0,0 +1,48 @@
+# Optimizer Endpoints
+
+## Purpose
+Document optimizer API endpoints for content optimization tasks.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/optimizer/urls.py`
+- Views: `backend/igny8_core/modules/optimizer/views.py`
+- Models/Services: `backend/igny8_core/business/optimization/models.py`, `services/*`
+
+## High-Level Responsibilities
+- Expose optimizer-related endpoints (as defined in `OptimizerViewSet`) to manage optimization tasks and results.
+
+## Detailed Behavior
+- Base path: `/api/v1/optimizer/`
+- Router registers root `OptimizerViewSet` (see module code for actions/fields).
+- Inherits base viewset scoping, unified responses, permissions, throttling defined in module views.
+
+## Data Structures / Models Involved (no code)
+- `OptimizationTask` and related optimization services.
+
+## Execution Flow
+- Requests → DRF auth → OptimizerViewSet → service logic → unified response.
+
+## Cross-Module Interactions
+- Operates on writer `Content`; may influence publishing readiness and optimization scores.
+
+## State Transitions
+- As defined by OptimizerViewSet actions (e.g., pending/running/completed/failed).
+
+## Error Handling
+- Standard unified responses and throttling.
+
+## Tenancy Rules
+- Inherits account/site scoping from base classes.
+
+## Billing Rules
+- Optimization credits are tracked in optimization tasks; deductions occur in billing services when AI optimization runs (see optimization module docs).
+
+## Background Tasks / Schedulers
+- Optimization runs may execute via services/Celery; endpoints trigger/manage these flows.
+
+## Key Design Considerations
+- Keep scoping intact; reuse services for optimization execution.
+
+## How Developers Should Work With This Module
+- Extend OptimizerViewSet with new actions as needed; ensure billing/credit checks are applied when adding AI-driven optimization.
+

docs/90-ARCHIVED/master-docs-original/20-api/ENDPOINTS/payments.md

@@ -0,0 +1,53 @@
+# Payments Endpoints
+
+## Purpose
+Document payment-related endpoints exposed under billing APIs.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/billing/urls.py`
+- Views: `backend/igny8_core/business/billing/views.py` (`PaymentViewSet`)
+
+## High-Level Responsibilities
+- List payments for the current account and submit manual payments tied to invoices.
+- Expose available payment methods per account/country configuration.
+
+## Detailed Behavior
+- Base path: `/api/v1/billing/`
+- `PaymentViewSet`:
+  - `GET /payments/` → list payments (account-scoped; optional status filter). Returns amount, currency, payment_method, status, timestamps, invoice linkage, transaction_reference, failure_reason.
+  - `GET /payment-methods/available/` → returns available methods (driven by `PaymentService.get_available_payment_methods`; includes methods array plus metadata).
+  - `POST /payments/manual/` → submit manual payment for an invoice:
+    - Body: `invoice_id`, `payment_method` (`bank_transfer` or `local_wallet`), `transaction_reference` (or `reference`), optional `notes`.
+    - Validates invoice belongs to account and is not already paid; creates payment via `PaymentService.create_manual_payment`; returns pending-approval status and payment id.
+- Permissions: authenticated users; account scoping via `request.user.account`.
+
+## Data Structures / Models Involved (no code)
+- `Payment`, `Invoice`, `Account`, `PaymentMethodConfig`, `AccountPaymentMethod`.
+
+## Execution Flow
+- Router dispatch → PaymentViewSet → service calls → model updates → unified responses. Manual payment creates a pending payment record for later approval/processing.
+
+## Cross-Module Interactions
+- Payments link to invoices; account scoping enforced. Available methods depend on payment method configs; manual payments may require admin follow-up.
+
+## State Transitions
+- Payments move through statuses (`pending`, `pending_approval`, `processing`, `succeeded/completed`, `failed`, `refunded`, `cancelled`).
+
+## Error Handling
+- 400 on missing required fields or already-paid invoice; 404 if invoice not found for account.
+
+## Tenancy Rules
+- All queries scoped to `request.user.account`; no cross-tenant access.
+
+## Billing Rules
+- Payment records tie to invoices; credit balance changes happen when payments are processed (handled in payment service/admin flows).
+
+## Background Tasks / Schedulers
+- None specific in endpoints; payment processing/approval handled by services/admin workflows.
+
+## Key Design Considerations
+- Manual payment endpoint avoids storing sensitive data; relies on transaction_reference and admin approval.
+
+## How Developers Should Work With This Module
+- Use manual payment endpoint for bank/local wallet flows; implement gateway flows (Stripe/PayPal) in `PaymentService` and add endpoints if needed; keep account scoping and invoice validation.
+