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