docs & ux improvmeents

docs/20-API/API-REFERENCE.md

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

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

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

@@ -1,77 +0,0 @@
-# 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/ENDPOINTS.md

@@ -0,0 +1,266 @@
+# API Endpoints Reference
+
+**Last Verified:** December 25, 2025  
+**Base URL:** `/api/v1/`  
+**Documentation:** `/api/docs/` (Swagger) | `/api/redoc/` (ReDoc)
+
+---
+
+## Authentication
+
+All endpoints require authentication unless noted.
+
+**Methods:**
+- `Authorization: Bearer <jwt_token>` - JWT token
+- `Authorization: ApiKey <key>` - API key (WordPress integration)
+- Session cookie (Django Admin)
+
+---
+
+## Auth Endpoints (`/api/v1/auth/`)
+
+| Method | Path | Handler | Auth | Purpose |
+|--------|------|---------|------|---------|
+| POST | `/register/` | `RegisterView` | ❌ | Create account |
+| POST | `/login/` | `LoginView` | ❌ | Get tokens |
+| POST | `/logout/` | `LogoutView` | ✅ | Invalidate session |
+| POST | `/token/refresh/` | `RefreshTokenView` | ✅ | Refresh access token |
+| POST | `/password/change/` | `ChangePasswordView` | ✅ | Change password |
+| POST | `/password/reset/` | `RequestPasswordResetView` | ❌ | Request reset email |
+| POST | `/password/reset/confirm/` | `ResetPasswordView` | ❌ | Confirm reset |
+| GET | `/groups/` | `RoleViewSet.list` | ✅ | List roles |
+| GET | `/users/` | `UserViewSet.list` | ✅ | List users |
+| POST | `/users/` | `UserViewSet.create` | ✅ | Create user |
+| GET | `/account/` | `AccountViewSet.retrieve` | ✅ | Get account |
+| PUT | `/account/` | `AccountViewSet.update` | ✅ | Update account |
+| GET | `/sites/` | `SiteViewSet.list` | ✅ | List sites |
+| POST | `/sites/` | `SiteViewSet.create` | ✅ | Create site |
+| GET | `/sectors/` | `SectorViewSet.list` | ✅ | List sectors |
+| POST | `/sectors/` | `SectorViewSet.create` | ✅ | Create sector |
+| GET | `/industries/` | `IndustryViewSet.list` | ✅ | List industries |
+| GET | `/seed-keywords/` | `SeedKeywordViewSet.list` | ✅ | List seed keywords |
+
+---
+
+## Planner Endpoints (`/api/v1/planner/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/keywords/` | `KeywordViewSet.list` | List keywords |
+| POST | `/keywords/` | `KeywordViewSet.create` | Create keyword |
+| GET | `/keywords/{id}/` | `KeywordViewSet.retrieve` | Get keyword |
+| PUT | `/keywords/{id}/` | `KeywordViewSet.update` | Update keyword |
+| DELETE | `/keywords/{id}/` | `KeywordViewSet.destroy` | Delete keyword |
+| POST | `/keywords/bulk_delete/` | `KeywordViewSet.bulk_delete` | Hard delete multiple |
+| POST | `/keywords/bulk_status/` | `KeywordViewSet.bulk_status` | Update status |
+| POST | `/keywords/add_to_workflow/` | `KeywordViewSet.add_to_workflow` | Add seed keywords |
+| GET | `/clusters/` | `ClusterViewSet.list` | List clusters |
+| POST | `/clusters/` | `ClusterViewSet.create` | Create cluster |
+| POST | `/clusters/auto_cluster/` | `ClusterViewSet.auto_cluster` | AI clustering |
+| POST | `/clusters/generate_ideas/` | `ClusterViewSet.generate_ideas` | Generate ideas |
+| GET | `/ideas/` | `ContentIdeaViewSet.list` | List ideas |
+| POST | `/ideas/` | `ContentIdeaViewSet.create` | Create idea |
+| POST | `/ideas/create_tasks/` | `ContentIdeaViewSet.create_tasks` | Convert to tasks |
+
+**Query Parameters:**
+- `?site_id=` - Filter by site
+- `?sector_id=` - Filter by sector
+- `?status=` - Filter by status
+- `?cluster_id=` - Filter by cluster
+- `?difficulty_min=`, `?difficulty_max=` - Difficulty range
+- `?volume_min=`, `?volume_max=` - Volume range
+
+---
+
+## Writer Endpoints (`/api/v1/writer/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/tasks/` | `TaskViewSet.list` | List tasks |
+| POST | `/tasks/` | `TaskViewSet.create` | Create task |
+| POST | `/tasks/bulk_create/` | `TaskViewSet.bulk_create` | Create multiple |
+| POST | `/tasks/{id}/generate_content/` | `TaskViewSet.generate_content` | AI generation |
+| GET | `/content/` | `ContentViewSet.list` | List content |
+| POST | `/content/` | `ContentViewSet.create` | Create content |
+| GET | `/content/{id}/` | `ContentViewSet.retrieve` | Get content |
+| PUT | `/content/{id}/` | `ContentViewSet.update` | Update content |
+| POST | `/content/{id}/update_content/` | `ContentViewSet.update_content` | Update with validation |
+| POST | `/content/{id}/generate_images/` | `ContentViewSet.generate_images` | Generate images |
+| POST | `/content/{id}/publish_to_wordpress/` | `ContentViewSet.publish_to_wordpress` | Publish to WP |
+| GET | `/images/` | `ImageViewSet.list` | List images |
+| POST | `/images/generate_for_content/` | `ImageViewSet.generate_for_content` | Generate images |
+| POST | `/images/regenerate/` | `ImageViewSet.regenerate` | Regenerate image |
+| GET | `/taxonomies/` | `TaxonomyViewSet.list` | List taxonomies |
+
+---
+
+## Billing Endpoints (`/api/v1/billing/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/balance/` | `CreditBalanceViewSet.list` | Current balance |
+| GET | `/usage/` | `CreditUsageViewSet.list` | Usage log |
+| GET | `/usage/summary/` | `CreditUsageViewSet.summary` | Usage summary |
+| GET | `/usage/limits/` | `CreditUsageViewSet.limits` | Plan limits |
+| GET | `/transactions/` | `TransactionViewSet.list` | Transaction history |
+
+---
+
+## Integration Endpoints (`/api/v1/integration/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/` | `SiteIntegrationViewSet.list` | List integrations |
+| POST | `/` | `SiteIntegrationViewSet.create` | Create integration |
+| PUT | `/{id}/` | `SiteIntegrationViewSet.update` | Update integration |
+| DELETE | `/{id}/` | `SiteIntegrationViewSet.destroy` | Delete integration |
+| POST | `/{id}/test_connection/` | Test connection | Verify credentials |
+| POST | `/{id}/test_collection_connection/` | Test collection | Test specific type |
+| POST | `/{id}/sync/` | Trigger sync | Start sync |
+| GET | `/{id}/sync_status/` | Sync status | Current progress |
+| POST | `/{id}/update_structure/` | Update structure | Refresh site data |
+| GET | `/{id}/content_types/` | Content types | Available types |
+| GET | `/{id}/sync_health/` | Sync health | Statistics |
+| POST | `/site_sync/` | Site-level sync | Sync by site ID |
+| POST | `/webhook/wordpress/` | WordPress webhook | Receive WP updates |
+
+---
+
+## System Endpoints (`/api/v1/system/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/settings/integrations/openai/` | Get OpenAI settings | Current config |
+| PUT | `/settings/integrations/openai/` | Save OpenAI settings | Update config |
+| GET | `/settings/integrations/image_generation/` | Get image settings | Current config |
+| PUT | `/settings/integrations/image_generation/` | Save image settings | Update config |
+| POST | `/settings/integrations/test/` | Test connection | Verify API keys |
+| GET | `/prompts/` | List prompts | All prompts |
+| GET | `/prompts/{type}/` | Get prompt | Specific prompt |
+| PUT | `/prompts/{type}/` | Save prompt | Update prompt |
+| POST | `/prompts/{type}/reset/` | Reset prompt | Reset to default |
+| GET | `/modules/` | Get modules | Module enable state |
+| PUT | `/modules/` | Save modules | Update enabled |
+| GET | `/health/` | Health check | System status |
+
+---
+
+## Automation Endpoints (`/api/v1/automation/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/config/` | Get config | Automation config |
+| PUT | `/update_config/` | Update config | Save settings |
+| POST | `/run_now/` | Run now | Start manual run |
+| GET | `/current_run/` | Current run | Run status |
+| GET | `/pipeline_overview/` | Pipeline | Stage counts |
+| GET | `/current_processing/` | Processing | Live status |
+| POST | `/pause/` | Pause | Pause run |
+| POST | `/resume/` | Resume | Resume run |
+| POST | `/cancel/` | Cancel | Cancel run |
+| GET | `/history/` | History | Past runs |
+| GET | `/logs/` | Logs | Activity log |
+| GET | `/estimate/` | Estimate | Credit estimate |
+
+**Query Parameters:** All require `?site_id=`, run-specific require `?run_id=`
+
+---
+
+## Linker Endpoints (`/api/v1/linker/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| POST | `/process/` | `LinkerViewSet.process` | Process single content |
+| POST | `/batch_process/` | `LinkerViewSet.batch_process` | Process multiple |
+
+---
+
+## Optimizer Endpoints (`/api/v1/optimizer/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| POST | `/optimize/` | `OptimizerViewSet.optimize` | Optimize content |
+| POST | `/batch_optimize/` | `OptimizerViewSet.batch_optimize` | Batch optimize |
+| POST | `/analyze/` | `OptimizerViewSet.analyze` | Analyze only |
+
+---
+
+## Publisher Endpoints (`/api/v1/publisher/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/records/` | `PublishingRecordViewSet.list` | List records |
+| POST | `/records/` | `PublishingRecordViewSet.create` | Create record |
+| GET | `/deployments/` | `DeploymentViewSet.list` | List deployments |
+| POST | `/publish/` | `PublishContentViewSet.publish` | Publish content |
+| GET | `/publish/status/` | `PublishContentViewSet.status` | Publish status |
+| GET | `/site-definition/` | `SiteDefinitionViewSet.list` | Public site def |
+
+---
+
+## Response Format
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "Optional message"
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Error message",
+  "code": "ERROR_CODE"
+}
+```
+
+### Paginated Response
+
+```json
+{
+  "count": 100,
+  "next": "http://api.igny8.com/api/v1/planner/keywords/?page=2",
+  "previous": null,
+  "results": [ ... ]
+}
+```
+
+---
+
+## HTTP Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 402 | Payment Required (insufficient credits) |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 429 | Rate Limited |
+| 500 | Server Error |
+
+---
+
+## Rate Limiting
+
+Rate limits are scoped by operation type:
+
+| Scope | Limit |
+|-------|-------|
+| AI operations | 60/min |
+| Content operations | 100/min |
+| Auth operations | 20/min |
+| General | 300/min |
+
+Rate limit headers included in responses:
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`

docs/20-API/INTEGRATION-ENDPOINTS.md

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

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

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