igny8/docs/10-MODULES/PLANNER.md

Planner Module

Last Verified: January 20, 2026
Version: 1.8.4
Status: ✅ Active
Backend Path: backend/igny8_core/modules/planner/
Frontend Path: frontend/src/pages/Planner/

---

Quick Reference

What	File	Key Items
Models	modules/planner/models.py	Keywords, Clusters, ContentIdeas
Views	modules/planner/views.py	KeywordViewSet, ClusterViewSet, ContentIdeaViewSet
Serializers	modules/planner/serializers.py	Keyword/Cluster/Idea serializers
AI Functions	ai/functions/clustering.py	AutoClusterFunction
AI Functions	ai/functions/ideas.py	GenerateIdeasFunction
Frontend Pages	pages/Planner/Keywords.tsx	Keyword management
Frontend Pages	pages/Planner/Clusters.tsx	Cluster management
Frontend Pages	pages/Planner/Ideas.tsx	Content ideas

---

Purpose

The Planner module manages the SEO content planning pipeline:

SeedKeywords (Global) → Keywords (Site/Sector) → Clusters → ContentIdeas → Tasks

---

Data Models

Keywords

Field	Type	Purpose
account	FK	Owner account
site	FK	Parent site
sector	FK	Parent sector
seed_keyword	FK	Reference to global SeedKeyword
keyword	CharField	Keyword text
search_volume	Integer	Monthly search volume
difficulty	Integer	SEO difficulty (0-100)
cpc	Decimal	Cost per click
search_intent	CharField	informational/commercial/transactional/navigational
status	CharField	new/mapped/used
cluster	FK	Assigned cluster (nullable)
created_at	DateTime	Creation date

Clusters

Field	Type	Purpose
account	FK	Owner account
site	FK	Parent site
sector	FK	Parent sector
name	CharField	Cluster name
description	TextField	Cluster description
primary_keyword	FK	Main keyword
status	CharField	draft/active/complete
keyword_count	Integer	Number of keywords
created_at	DateTime	Creation date

ContentIdeas

Field	Type	Purpose
account	FK	Owner account
site	FK	Parent site
sector	FK	Parent sector
cluster	FK	Source cluster
title	CharField	Content title
description	TextField	Content brief
target_keywords	JSON	Keywords to target
content_type	CharField	blog_post/guide/comparison/etc.
word_count_target	Integer	Target word count
status	CharField	draft/queued/used
priority	Integer	Priority score
created_at	DateTime	Creation date

---

API Endpoints

Keywords

Method	Path	Handler	Purpose
GET	/api/v1/planner/keywords/	KeywordViewSet.list	List keywords with filtering
POST	/api/v1/planner/keywords/	KeywordViewSet.create	Create single keyword
GET	/api/v1/planner/keywords/{id}/	KeywordViewSet.retrieve	Get keyword detail
PUT	/api/v1/planner/keywords/{id}/	KeywordViewSet.update	Update keyword
DELETE	/api/v1/planner/keywords/{id}/	KeywordViewSet.destroy	Soft delete keyword
POST	/api/v1/planner/keywords/bulk_delete/	KeywordViewSet.bulk_delete	Hard delete multiple
POST	/api/v1/planner/keywords/bulk_status/	KeywordViewSet.bulk_status	Update status for multiple
POST	/api/v1/planner/keywords/add_to_workflow/	KeywordViewSet.add_to_workflow	Add SeedKeywords to workflow

Filters: ?site_id=, ?sector_id=, ?status=, ?cluster_id=, ?difficulty_min=, ?difficulty_max=, ?volume_min=, ?volume_max=

Clusters

Method	Path	Handler	Purpose
GET	/api/v1/planner/clusters/	ClusterViewSet.list	List clusters
POST	/api/v1/planner/clusters/	ClusterViewSet.create	Create cluster manually
POST	/api/v1/planner/clusters/auto_cluster/	ClusterViewSet.auto_cluster	AI-powered clustering
POST	/api/v1/planner/clusters/generate_ideas/	ClusterViewSet.generate_ideas	Generate ideas from clusters

Content Ideas

Method	Path	Handler	Purpose
GET	/api/v1/planner/ideas/	ContentIdeaViewSet.list	List ideas
POST	/api/v1/planner/ideas/	ContentIdeaViewSet.create	Create idea manually
POST	/api/v1/planner/ideas/create_tasks/	ContentIdeaViewSet.create_tasks	Convert ideas to tasks

---

Business Logic

Auto Clustering (AI)

Trigger: User clicks "Auto Cluster" button
AI Function: AutoClusterFunction
Credit Cost: Based on AI tokens used (see AIModelConfig)

Flow:

1. User selects keywords (or all unclustered)
2. Frontend calls POST /clusters/auto_cluster/
3. Backend validates minimum 5 keywords
4. AIEngine executes AutoClusterFunction:
   • Sends keywords to GPT-4
   • AI groups by semantic similarity
   • Returns cluster assignments
5. Creates/updates Clusters records
6. Assigns keywords to clusters
7. Returns created clusters

Generate Ideas (AI)

Trigger: User clicks "Generate Ideas" on cluster(s)
AI Function: GenerateIdeasFunction
Credit Cost: Based on AI tokens used (see AIModelConfig)

Flow:

1. User selects clusters
2. Frontend calls POST /clusters/generate_ideas/
3. Backend validates clusters have keywords
4. AIEngine executes GenerateIdeasFunction:
   • Analyzes cluster keywords
   • Generates content titles + briefs
   • Suggests word counts and content types
5. Creates ContentIdeas records
6. Returns created ideas

Add Keywords to Workflow

Trigger: User selects SeedKeywords in setup
Credit Cost: None

Flow:

1. User browses global SeedKeywords
2. Selects keywords to add to their sector
3. Frontend calls POST /keywords/add_to_workflow/
4. Backend creates Keywords records linked to SeedKeywords
5. Keywords appear in Planner for clustering

---

Frontend Pages

Keywords Page (/planner/keywords)

• Table of all keywords with filtering
• Bulk actions: delete, update status
• Add keywords from SeedKeyword library
• Import keywords from CSV
• Assign to clusters manually

Clusters Page (/planner/clusters)

• Grid/list of clusters
• Auto-cluster action (AI)
• Generate ideas action (AI)
• View keywords in cluster
• Cluster status management

Ideas Page (/planner/ideas)

• Table of content ideas
• Convert to tasks action
• Edit idea details
• Priority management

---

Integration Points

From	To	Trigger
SeedKeywords	Keywords	Add to workflow
Keywords	Clusters	Auto clustering
Clusters	ContentIdeas	Generate ideas
ContentIdeas	Tasks	Create tasks
Automation Stage 1	Clusters	Automated clustering
Automation Stage 2	ContentIdeas	Automated idea generation

---

Common Issues

Issue	Cause	Fix
Clustering fails	Less than 5 keywords	Ensure minimum keywords
Ideas not generating	Cluster has no keywords	Assign keywords to cluster
Keywords not showing	Wrong site/sector filter	Check active site/sector
Duplicate keywords	Same keyword added twice	Check seed_keyword reference

---

Planned Changes

Feature	Status	Description
Keyword import improvements	🔜 Planned	Better CSV parsing and validation
Cluster merging	🔜 Planned	Merge similar clusters
Idea prioritization	🔜 Planned	AI-based priority scoring