296 lines
9.1 KiB
Markdown
296 lines
9.1 KiB
Markdown
# 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 |
|