revamps docs complete

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