# Publisher Module

**Last Verified:** January 3, 2026  
**Status:** ✅ Active  
**Version:** 1.3.2
**Backend Path:** `backend/igny8_core/modules/publisher/` + `backend/igny8_core/business/publishing/`  
**Frontend Path:** `frontend/src/pages/Publisher/`

---

## Quick Reference

| What | File | Key Items |
|------|------|-----------|
| Views | `modules/publisher/views.py` | `PublishingRecordViewSet`, `DeploymentViewSet`, `PublishContentViewSet` |
| Models | `business/publishing/models.py` | `PublishingRecord`, `DeploymentRecord` |
| Integration Models | `modules/integration/models.py` | `PublishingSettings` |
| Services | `business/publishing/services/*.py` | Publishing orchestration |
| Scheduler Tasks | `igny8_core/tasks/publishing_scheduler.py` | Celery beat tasks |
| URLs | `modules/publisher/urls.py` | Publisher endpoints |
| Frontend | `pages/Publisher/ContentCalendar.tsx` | Content calendar view |

---

## Purpose

The Publisher module manages:
- Content publishing pipeline
- **Publishing scheduler (automated publishing)**
- Publishing record tracking
- Deployment management
- Multi-destination publishing
- **Content calendar visualization**

---

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

### PublishingSettings (v1.3.2)

Site-level publishing configuration:

| Field | Type | Purpose |
|-------|------|---------|
| site | OneToOne | Parent site (unique) |
| auto_approval_enabled | Boolean | Auto-approve content |
| auto_publish_enabled | Boolean | Auto-publish approved content |
| daily_publish_limit | Integer | Max publications per day |
| weekly_publish_limit | Integer | Max publications per week |
| monthly_publish_limit | Integer | Max publications per month |
| publish_days | JSON | Days of week for publishing ["mon","wed","fri"] |
| publish_time_slots | JSON | Time slots for publishing [{"start":"09:00","end":"17:00"}] |

### Content Site Status Fields (v1.3.2)

Added to Content model for scheduling:

| Field | Type | Values |
|-------|------|--------|
| site_status | CharField | not_published, scheduled, publishing, published, failed |
| scheduled_publish_at | DateTime | Future publication time (nullable) |
| site_status_updated_at | DateTime | Last status change timestamp |

---

## 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 |
| **POST** | `/api/v1/content/{id}/schedule/` | Schedule content | Schedule content for future publish |
| **POST** | `/api/v1/content/{id}/unschedule/` | Unschedule content | Remove from publishing schedule |
| **GET** | `/api/v1/sites/{site_id}/publishing-settings/` | `PublishingSettingsViewSet` | Get site publishing settings |
| **PUT** | `/api/v1/sites/{site_id}/publishing-settings/` | `PublishingSettingsViewSet` | Update publishing settings |

---

## Publishing Scheduler (v1.3.2)

### Celery Beat Tasks

Located in `igny8_core/tasks/publishing_scheduler.py`:

| Task | Schedule | Purpose |
|------|----------|---------|
| `schedule_approved_content` | Every 15 minutes | Assigns publish times to approved content |
| `process_scheduled_publications` | Every 5 minutes | Publishes content when scheduled time arrives |
| `cleanup_failed_publications` | Daily at midnight | Retries or cleans up failed publications |

### Scheduling Flow

```
Approved Content → schedule_approved_content (every 15 min)
                        ↓
            Check PublishingSettings
                        ↓
            Assign scheduled_publish_at based on:
            - publish_days configuration
            - publish_time_slots configuration  
            - daily/weekly/monthly limits
                        ↓
            Set site_status = "scheduled"
                        ↓
process_scheduled_publications (every 5 min)
                        ↓
            If scheduled_publish_at <= now:
            - Set site_status = "publishing"
            - Execute publication
            - Set site_status = "published" or "failed"
```

### Site Status State Machine

```
not_published → scheduled → publishing → published
                    ↓              ↓
                    ↓         → failed
                    ↓
              not_published (if unscheduled)
```

---

## Frontend Pages (v1.3.2)

### Content Calendar (`/publisher/content-calendar`)

**Purpose:** Visualize and manage scheduled content

**Features:**
- Calendar view of scheduled publications
- List view alternative
- Filter by site
- Schedule/unschedule actions
- Drag-and-drop rescheduling (planned)

**Components:**
- `ContentCalendar.tsx` - Main page component
- `CalendarItemTooltip` - Hover details for calendar items
- `SiteInfoBar` - Site context header

### Publishing Queue (`/publisher/publishing-queue`)

**Purpose:** Review upcoming publications

**Features:**
- List of content pending publication
- Status indicators (scheduled, publishing, failed)
- Publish now / unschedule actions

---

## 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~~ | ✅ Implemented (v1.3.2) | Future-date publishing |
| Republish detection | 🔜 Planned | Detect and handle updates |
| ~~Publishing queue~~ | ✅ Implemented (v1.3.2) | Batch publishing with queue |
| Drag-and-drop calendar | 🔜 Planned | Reschedule via drag-and-drop |