# Publisher Module

**Last Verified:** December 25, 2025  
**Status:** ✅ Active  
**Backend Path:** `backend/igny8_core/modules/publisher/` + `backend/igny8_core/business/publishing/`  
**Frontend Path:** N/A (API-only module)

---

## Quick Reference

| What | File | Key Items |
|------|------|-----------|
| Views | `modules/publisher/views.py` | `PublishingRecordViewSet`, `DeploymentViewSet`, `PublishContentViewSet` |
| Models | `business/publishing/models.py` | `PublishingRecord`, `DeploymentRecord` |
| Services | `business/publishing/services/*.py` | Publishing orchestration |
| URLs | `modules/publisher/urls.py` | Publisher endpoints |

---

## Purpose

The Publisher module manages:
- Content publishing pipeline
- Publishing record tracking
- Deployment management
- Multi-destination publishing

---

## Data Models

### PublishingRecord

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Parent site |
| content | FK | Source content |
| destination | CharField | wordpress/ghost/webflow |
| external_id | CharField | ID on destination platform |
| external_url | URLField | Published URL |
| status | CharField | pending/published/failed/retracted |
| published_at | DateTime | Publication time |
| metadata | JSON | Additional data |
| created_at | DateTime | Record creation |

### DeploymentRecord

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Target site |
| deployment_type | CharField | full/incremental |
| status | CharField | pending/deploying/completed/failed |
| items_deployed | Integer | Number of items |
| started_at | DateTime | Start time |
| completed_at | DateTime | Completion time |
| error_log | TextField | Errors encountered |
| metadata | JSON | Deployment details |

---

## API Endpoints

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/api/v1/publisher/records/` | `PublishingRecordViewSet.list` | List publishing records |
| POST | `/api/v1/publisher/records/` | `PublishingRecordViewSet.create` | Create record |
| GET | `/api/v1/publisher/deployments/` | `DeploymentViewSet.list` | List deployments |
| POST | `/api/v1/publisher/publish/` | `PublishContentViewSet.publish` | Publish content |
| GET | `/api/v1/publisher/publish/status/` | `PublishContentViewSet.status` | Get publishing status |
| GET | `/api/v1/publisher/site-definition/` | `SiteDefinitionViewSet.list` | Public site definitions |

---

## Publishing Flow

### Single Content Publish

**Trigger:** User clicks "Publish" or API call  
**Flow:**
1. Validate content is in publishable state
2. Get site integration credentials
3. Transform content for destination:
   - Format HTML for platform
   - Process images
   - Map taxonomies
4. Push to destination API
5. Create `PublishingRecord` with external ID
6. Update Content status to `published`

### Batch Deployment

**Trigger:** Deployment action  
**Flow:**
1. Create `DeploymentRecord`
2. Gather all pending content
3. Process each item:
   - Publish to destination
   - Create publishing record
   - Update content status
4. Update deployment status
5. Log any errors

---

## Destination Adapters

### WordPress Adapter

- Uses WordPress REST API
- Supports posts, pages, custom post types
- Handles media upload
- Maps categories/tags

### Ghost Adapter (Planned)

- Ghost Admin API integration
- Post publishing
- Image handling

### Webflow Adapter (Planned)

- Webflow CMS API
- Collection item publishing
- Asset management

---

## Publishing States

| Status | Description |
|--------|-------------|
| pending | Ready to publish |
| published | Successfully published |
| failed | Publishing failed |
| retracted | Unpublished/removed |

---

## Site Definition Endpoint

**Purpose:** Public endpoint for headless CMS use cases

Returns site structure for external consumption:
- Site metadata
- Available taxonomies
- Content types
- URL structure

---

## Integration Points

| From | To | Trigger |
|------|----|---------| 
| Writer | Publisher | Publish action |
| Automation Stage 7 | Publisher | Auto-publish (future) |
| Publisher | Integrations | Destination APIs |
| Publisher | Content | Status updates |

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| Publish failed | Invalid credentials | Check integration settings |
| Duplicate posts | Published twice | Check existing publishing record |
| Images missing | Upload failed | Check media library access |
| Wrong category | Mapping issue | Verify taxonomy sync |

---

## Planned Changes

| Feature | Status | Description |
|---------|--------|-------------|
| Ghost integration | 🔜 Planned | Ghost CMS publishing |
| Webflow integration | 🔜 Planned | Webflow publishing |
| Scheduled publishing | 🔜 Planned | Future-date publishing |
| Republish detection | 🔜 Planned | Detect and handle updates |
| Publishing queue | 🔜 Planned | Batch publishing with queue |