igny8/docs/10-MODULES/PUBLISHER.md

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