revamps docs complete

master-docs/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.

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/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.
+

master-docs/20-api/ENDPOINTS/planner.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.
+

master-docs/20-api/ENDPOINTS/publisher.md

@@ -0,0 +1,53 @@
+# Publisher Endpoints
+
+## Purpose
+Document publisher API endpoints for publishing records and deployments.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/publisher/urls.py`
+- Viewsets: `backend/igny8_core/modules/publisher/views.py`
+- Models: `backend/igny8_core/business/publishing/models.py`
+
+## High-Level Responsibilities
+- Expose CRUD for publishing records (content publishing to destinations) and deployment records (site deployments).
+- Scope resources by account/site/sector and provide unified responses.
+
+## Detailed Behavior
+- Base path: `/api/v1/publisher/`
+- Routers register:
+  - `publishing-records/` → `PublishingRecordViewSet`
+  - `deployments/` → `DeploymentRecordViewSet`
+  - Root publisher viewset (`PublisherViewSet`) for additional publisher actions (see module code).
+- Viewsets inherit account/site/sector filtering via base classes; permissions/throttles defined in module views.
+- Publishing records track destination/status/URLs/errors; deployments track versions/status/URL/metadata.
+
+## Data Structures / Models Involved (no code)
+- `PublishingRecord`, `DeploymentRecord`, `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base scoping → serializer validation → model CRUD → unified responses.
+
+## Cross-Module Interactions
+- Publishing records reference writer content; deployments reference sites; integration data may influence destinations (see integration/publishing services).
+
+## State Transitions
+- Publishing status: pending/publishing/published/failed; Deployment status: pending/deploying/deployed/failed/rolled_back.
+
+## Error Handling
+- Unified responses; validation errors for missing/invalid fields; standard 4xx/5xx on failures.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector via base viewsets and permissions; privileged roles may bypass filtering but data retains tenant fields.
+
+## Billing Rules
+- None directly in publisher endpoints; any credit usage would occur in upstream AI flows.
+
+## Background Tasks / Schedulers
+- None specific in endpoints; deployments/publishing actions may be driven by services or Celery tasks elsewhere.
+
+## Key Design Considerations
+- Separation of publishing records and deployment records keeps content publishing and site deployment distinct.
+
+## How Developers Should Work With This Module
+- Use existing viewsets; maintain site/sector scoping and unified response patterns when extending publisher functionality.
+

master-docs/20-api/ENDPOINTS/sites.md

@@ -0,0 +1,71 @@
+# Site Endpoints
+
+## Purpose
+Document site management endpoints under the auth module, including creation, listing, sector selection, and activation.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/auth/urls.py`
+- Views: `backend/igny8_core/auth/views.py` (`SiteViewSet`)
+- Serializers: `backend/igny8_core/auth/serializers.py` (`SiteSerializer`, `SectorSerializer`)
+
+## High-Level Responsibilities
+- CRUD for sites scoped to an account, with role-based access.
+- Allow public read by slug for active sites (renderer support).
+- Manage sector selection and activation per site.
+
+## Detailed Behavior
+- Base path: `/api/v1/auth/sites/`
+- Permissions:
+  - `list` with slug filter: `AllowAny` (public read by slug, active sites only).
+  - `create`: authenticated users (viewer+); sets site account from request/user.
+  - Other actions: `IsEditorOrAbove` with tenant access.
+- Queryset logic:
+  - Unauthenticated with `slug` query param: returns active site by slug.
+  - Authenticated admin/developer: all sites.
+  - Authenticated owner/admin: sites for user’s account.
+  - Other users: sites where they have `SiteUserAccess`.
+- Actions:
+  - `GET /sites/` list (with filters above).
+  - `POST /sites/` create site; account set from request/user.
+  - `GET /sites/{id}/sectors/` list active sectors for the site.
+  - `POST /sites/{id}/set_active/` marks site active (no deactivation of others).
+  - `POST /sites/{id}/select_sectors/` sets industry and sectors:
+    - Requires `industry_slug`; optional `sector_slugs` list.
+    - Validates industry exists/active; enforces plan sector limit (`get_max_sectors_limit`).
+    - Deactivates sectors not in provided list; ensures sectors belong to industry; creates missing site sectors as needed; returns site + sectors.
+- Create/update:
+  - `perform_create` sets account; no single-active constraint.
+  - `perform_update` retains account; no single-active constraint.
+
+## Data Structures / Models Involved (no code)
+- `Site`, `Sector`, `Industry`, `IndustrySector`, `Plan` (for sector limits), `SiteUserAccess`, `Account`.
+
+## Execution Flow
+- Requests → DRF auth (JWT/session) → permissions → queryset scoping → serializer validation → model ops → unified response. Public slug reads bypass account filtering.
+
+## Cross-Module Interactions
+- Sites link to planner/writer records via site/sector; integration uses `Site.wp_api_key`; plan sector limits referenced here.
+
+## State Transitions
+- Site activation via `set_active`; sector activation/deactivation via `select_sectors`; industry assignment updated on selection.
+
+## Error Handling
+- 400 for missing industry slug or exceeding sector limits; 404 for missing site/industry; 500 if site lacks account when selecting sectors.
+
+## Tenancy Rules
+- Account-scoped except public slug read; role-based overrides for admins/developers; SiteUserAccess governs non-admin access.
+
+## Billing Rules
+- Sector limit enforced from plan (`max_industries` via `get_max_sectors_limit`).
+
+## Background Tasks / Schedulers
+- None in site endpoints.
+
+## Key Design Considerations
+- Public slug access supports site renderer without auth.
+- Sector selection enforces industry/plan constraints and deactivates unselected sectors.
+
+## How Developers Should Work With This Module
+- Use `select_sectors` to set industry/sector with plan-aware limits.
+- When extending site data, keep public slug path safe and scoped to active sites; maintain role-based access controls.
+

master-docs/20-api/ENDPOINTS/system.md

@@ -0,0 +1,61 @@
+# System Endpoints
+
+## Purpose
+Document system module endpoints for AI prompts, author profiles, strategies, and system/settings resources.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/system/urls.py`
+- Views: `backend/igny8_core/modules/system/views.py`
+- Models/serializers: `backend/igny8_core/modules/system/models.py`, `serializers.py`
+
+## High-Level Responsibilities
+- Manage account-scoped AI prompts, author profiles, and strategies.
+- Expose system/user/module/AI settings endpoints.
+- Provide prompt retrieval by type and save/reset helpers with role checks.
+
+## Detailed Behavior
+- Base path: `/api/v1/system/`
+- Routers register:
+  - `prompts/` → `AIPromptViewSet` (CRUD, `by_type`, `save_prompt`, `reset_prompt`)
+  - `author-profiles/` → `AuthorProfileViewSet` (CRUD)
+  - `strategies/` → `StrategyViewSet` (CRUD)
+  - `settings/system`, `settings/account`, `settings/user`, `settings/modules`, `settings/ai` → respective settings viewsets
+- AIPromptViewSet:
+  - Permissions: `IsAuthenticatedAndActive`, `HasTenantAccess`; throttle scope `system`; paginated.
+  - `by_type` returns prompt by prompt_type, or default when missing.
+  - `save_prompt`/`reset_prompt` require editor-or-above; set/read account from request/user or first account fallback (dev).
+  - Queryset ordered by prompt_type.
+- Settings viewsets expose retrieve/update for their scope (system/account/user/modules/ai). Permissions and scoping follow AccountModelViewSet.
+- AuthorProfile/Strategy viewsets provide standard CRUD under account scoping.
+
+## Data Structures / Models Involved (no code)
+- `AIPrompt` (prompt_type, prompt_value, default_prompt, is_active), `AuthorProfile`, `Strategy`, settings models.
+
+## Execution Flow
+- Requests → DRF auth → AccountModelViewSet filtering → serializer validation → model CRUD → unified responses. Custom actions handle prompt save/reset/type lookups.
+
+## Cross-Module Interactions
+- Prompts are consumed by AI functions; settings may influence module behavior (e.g., AI config).
+
+## State Transitions
+- Prompt updates, resets; settings updates; author profile/strategy CRUD.
+
+## Error Handling
+- Unified errors; 403 when lacking editor role for prompt save/reset; 400 on missing prompt_type/value.
+
+## Tenancy Rules
+- All resources are account scoped via AccountModelViewSet and permissions.
+
+## Billing Rules
+- None; prompts/settings do not affect credits directly.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- Prompt defaults are returned when custom prompt missing to keep AI flows resilient.
+- Editor-or-above requirement protects prompt modifications.
+
+## How Developers Should Work With This Module
+- Use provided viewsets/actions; ensure account context is set. Extend settings endpoints by adding serializers/models and wiring to the router.
+

master-docs/20-api/ENDPOINTS/writer.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.
+

master-docs/20-api/REST-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.