docs & ux improvmeents

2025-12-25 20:31:58 +00:00
parent 90e6e96b2b
commit 4bffede052
247 changed files with 6869 additions and 53517 deletions
--- a/docs/10-MODULES/PUBLISHER.md
+++ b/docs/10-MODULES/PUBLISHER.md
@@ -0,0 +1,184 @@
+# 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 |