# Writer Module

**Last Verified:** December 27, 2025  
**Version:** 1.2.0  
**Status:** ✅ Active  
**Backend Path:** `backend/igny8_core/modules/writer/`  
**Frontend Path:** `frontend/src/pages/Writer/`

---

## Quick Reference

| What | File | Key Items |
|------|------|-----------|
| Models | `modules/writer/models.py` | `Tasks`, `Content`, `Images`, `ContentTaxonomy` |
| Views | `modules/writer/views.py` | `TaskViewSet`, `ContentViewSet`, `ImageViewSet` |
| AI Functions | `ai/functions/content.py` | `GenerateContentFunction` |
| AI Functions | `ai/functions/images.py` | `GenerateImagesFunction`, `GenerateImagePromptsFunction` |
| Frontend Pages | `pages/Writer/Tasks.tsx` | Task management |
| Frontend Pages | `pages/Writer/Content.tsx` | Content listing |
| Frontend Pages | `pages/Writer/ContentViewer.tsx` | Content preview/edit |

---

## Purpose

The Writer module manages the content creation pipeline:

```
ContentIdeas → Tasks → Content → Images → Review → Publish
```

---

## Data Models

### Tasks

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Parent site |
| sector | FK | Parent sector |
| content_idea | FK | Source idea (nullable) |
| title | CharField | Task/content title |
| description | TextField | Task brief |
| target_keywords | JSON | Keywords to target |
| content_type | CharField | blog_post/guide/comparison/etc. |
| word_count_target | Integer | Target word count |
| status | CharField | pending/in_progress/completed/cancelled |
| assigned_to | FK | Assigned user (nullable) |
| due_date | DateTime | Due date (nullable) |
| priority | Integer | Priority level |
| created_at | DateTime | Creation date |

### Content

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Parent site |
| sector | FK | Parent sector |
| task | FK | Source task (nullable) |
| title | CharField | Content title |
| slug | SlugField | URL slug |
| content_body | TextField | HTML content |
| excerpt | TextField | Short summary |
| meta_title | CharField | SEO meta title |
| meta_description | CharField | SEO meta description |
| word_count | Integer | Actual word count |
| status | CharField | draft/review/approved/published |
| content_type | CharField | post/page/product |
| content_structure | CharField | article/guide/comparison/review/listicle |
| source | CharField | igny8/wordpress/manual |
| wordpress_id | Integer | WP post ID (if synced) |
| published_at | DateTime | Publication date |
| created_at | DateTime | Creation date |

### Images

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Parent site |
| sector | FK | Parent sector |
| content | FK | Parent content |
| image_type | CharField | featured/desktop/mobile/in_article |
| prompt | TextField | Generation prompt |
| image_url | URLField | Image URL |
| alt_text | CharField | Alt text for SEO |
| status | CharField | pending/generating/completed/failed |
| position | Integer | Order for in-article images |
| provider | CharField | dalle/runware |
| model | CharField | dall-e-3/runware:97@1 |
| created_at | DateTime | Creation date |

### ContentTaxonomy

| Field | Type | Purpose |
|-------|------|---------|
| account | FK | Owner account |
| site | FK | Parent site |
| name | CharField | Category/tag name |
| slug | SlugField | URL slug |
| taxonomy_type | CharField | category/tag |
| parent | FK | Parent taxonomy (for hierarchy) |
| description | TextField | Description |
| wordpress_id | Integer | WP term ID (if synced) |

---

## API Endpoints

### Tasks

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/api/v1/writer/tasks/` | `TaskViewSet.list` | List tasks |
| POST | `/api/v1/writer/tasks/` | `TaskViewSet.create` | Create task |
| POST | `/api/v1/writer/tasks/bulk_create/` | `TaskViewSet.bulk_create` | Create multiple tasks |
| POST | `/api/v1/writer/tasks/{id}/generate_content/` | `TaskViewSet.generate_content` | AI content generation |

### Content

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/api/v1/writer/content/` | `ContentViewSet.list` | List content |
| POST | `/api/v1/writer/content/` | `ContentViewSet.create` | Create content manually |
| PUT | `/api/v1/writer/content/{id}/` | `ContentViewSet.update` | Update content |
| POST | `/api/v1/writer/content/{id}/update_content/` | `ContentViewSet.update_content` | Update with validation |
| POST | `/api/v1/writer/content/{id}/generate_images/` | `ContentViewSet.generate_images` | Generate images |
| POST | `/api/v1/writer/content/{id}/publish_to_wordpress/` | `ContentViewSet.publish_to_wordpress` | Publish to WP |

### Images

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/api/v1/writer/images/` | `ImageViewSet.list` | List images |
| POST | `/api/v1/writer/images/generate_for_content/` | `ImageViewSet.generate_for_content` | Generate images |
| POST | `/api/v1/writer/images/regenerate/` | `ImageViewSet.regenerate` | Regenerate image |

---

## Business Logic

### Content Generation (AI)

**Trigger:** User clicks "Generate" on task  
**AI Function:** `GenerateContentFunction`  
**Credit Cost:** Per 100 words generated

**Flow:**
1. User has task with title, keywords, word count target
2. Frontend calls `POST /tasks/{id}/generate_content/`
3. Backend validates task and credits
4. AIEngine executes `GenerateContentFunction`:
   - Loads account's AI prompts and strategy
   - Sends to GPT-4 with structured output
   - Receives HTML content with proper structure
5. Creates `Content` record linked to task
6. Updates task status to `completed`
7. Returns content for review

### Image Prompt Generation (AI)

**Trigger:** Part of content generation or explicit  
**AI Function:** `GenerateImagePromptsFunction`  
**Credit Cost:** Per prompt

**Flow:**
1. Content exists with body
2. AI analyzes content sections
3. Generates prompts for:
   - Featured image (1)
   - In-article images (configurable count)
4. Creates `Images` records with prompts, status=pending

### Image Generation (AI)

**Trigger:** User clicks "Generate Images" or automation  
**AI Function:** `GenerateImagesFunction`  
**Credit Cost:** Per image

**Flow:**
1. Image record exists with prompt, status=pending
2. Backend calls DALL-E or Runware API
3. Receives image URL
4. Updates `Images` record with URL, status=completed

### WordPress Publishing

**Trigger:** User clicks "Publish to WordPress"  
**Credit Cost:** None

**Flow:**
1. Content is in `approved` status
2. Site has WordPress integration configured
3. Backend calls WordPress REST API:
   - Creates/updates post
   - Uploads featured image
   - Sets categories/tags
4. Updates Content with `wordpress_id`
5. Sets status to `published`

---

## Content Structures

| Structure | Purpose | Typical Sections |
|-----------|---------|------------------|
| article | General blog post | Intro, Body, Conclusion |
| guide | How-to content | Steps, Tips, Summary |
| comparison | Product comparison | Features, Pros/Cons, Verdict |
| review | Product review | Overview, Features, Rating |
| listicle | List-based content | Numbered items with details |
| pillar | Long-form authority | Multiple sections with depth |

---

## Frontend Pages

### Tasks Page (`/writer/tasks`)

- Table of all tasks
- Filter by status, assigned user
- Generate content action
- Bulk actions

### Content Page (`/writer/content`)

- Table of all content
- Filter by status, content type
- Quick preview
- Publish actions

### Content Viewer (`/writer/content/{id}`)

- Full content preview
- Edit mode
- Image management
- Publish to WordPress
- Status management

### Draft/Review/Approved Tabs

- Filtered views by status
- Different actions per status
- **v1.2.0**: "Published" tab renamed to "Approved"

---

## Content Status Flow

```
draft → review → approved → published
                    ↓
              (rejected) → draft (revision)
```

---

## Integration Points

| From | To | Trigger |
|------|----|---------| 
| ContentIdeas | Tasks | Create tasks |
| Tasks | Content | Generate content |
| Content | Images | Generate images |
| Content | WordPress | Publish |
| WordPress | Content | Sync imports |
| Automation Stage 4 | Content | Automated generation |
| Automation Stage 5-6 | Images | Automated image generation |

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| Content too short | Low word count target | Increase target in task |
| Images not generating | No prompts created | Run image prompt generation first |
| WordPress publish fails | Invalid credentials | Check integration settings |
| Content stuck in draft | No manual status update | Update status via UI or API |
| Duplicate content | Re-running generation | Check if content already exists |

---

## Planned Changes

| Feature | Status | Description |
|---------|--------|-------------|
| Content revisions | 🔜 Planned | Track content version history |
| Multi-language | 🔜 Planned | Generate content in different languages |
| Batch generation | 🔜 Planned | Generate multiple content pieces at once |
| Regenerate sections | 🔜 Planned | AI regenerate specific sections |