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