salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
062d09d89917600dcf89d15961c6e649251405ed
igny8/docs/06-FEATURE-MODIFICATION-DEVELOPER-GUIDE.md
alorig 062d09d899 docs-complete
2025-11-29 22:52:34 +05:00

1122 lines
34 KiB
Markdown
Raw Blame History

# Feature Modification & Development Guide
## Complete File Reference for Adding, Modifying, and Removing Features
**Version:** 1.0.0
**Last Updated:** November 29, 2025
**Purpose:** Quick reference for developers to locate exactly which files to modify for specific feature types, across both frontend and backend.
---
## Table of Contents
1. [Quick Navigation by Feature Type](#quick-navigation-by-feature-type)
2. [Feature Type Reference Matrix](#feature-type-reference-matrix)
3. [Frontend Feature Modifications](#frontend-feature-modifications)
4. [Backend Feature Modifications](#backend-feature-modifications)
5. [Cross-Module Modifications](#cross-module-modifications)
6. [Database Schema Changes](#database-schema-changes)
7. [Common Workflow Patterns](#common-workflow-patterns)
8. [File Organization Index](#file-organization-index)
---
## Quick Navigation by Feature Type
### 🎯 Find Your Feature Type
- **Adding/Removing/Modifying a Database Column** → [Database Changes](#database-changes)
- **Adding a New Page/List View** → [New Page Feature](#new-page-feature)
- **Adding a Column to a Table/List** → [Table Column Addition](#table-column-addition)
- **Adding a Form Field** → [Form Field Addition](#form-field-addition)
- **Adding an API Endpoint** → [API Endpoint Addition](#api-endpoint-addition)
- **Adding a Filter/Search** → [Filter/Search Addition](#filtersearch-addition)
- **Adding a Status/Choice Field** → [Status Field Addition](#status-field-addition)
- **Modifying API Response** → [API Response Modification](#api-response-modification)
- **Adding Validation** → [Validation Addition](#validation-addition)
- **Adding Background Task** → [Background Task Addition](#background-task-addition)
- **Adding Webhook** → [Webhook Addition](#webhook-addition)
- **Adding Integration** → [Integration Addition](#integration-addition)
---
## Feature Type Reference Matrix
| Feature Type | Frontend Files | Backend Files | Database | Global Config |
|--------------|---|---|---|---|
| **Database Column** | - | Model + Serializer | Migration | - |
| **Table Column** | List Component | ViewSet Filter | - | - |
| **Form Field** | Form Component | Serializer | Model Migration | - |
| **Page/View** | Page Component | ViewSet | - | Routes |
| **API Endpoint** | API Hook | ViewSet + Router | - | urls.py |
| **Status Field** | Select/Enum | Model Choice | Migration | - |
| **Filter/Search** | Filter UI | filterset_fields | Index | - |
| **Validation** | Form Rules | Validator Service | - | - |
| **Background Task** | UI Trigger | Celery Task | - | settings.py |
| **Webhook** | - | Handler Function | WebhookLog Model | urls.py |
| **Integration** | - | Adapter Class | Integration Model | - |
---
## Frontend Feature Modifications
### Directory Structure
```
frontend/src/
├── pages/
│ ├── Planner/
│ │ ├── Dashboard.tsx
│ │ ├── Keywords.tsx
│ │ ├── Clusters.tsx
│ │ ├── ClusterDetail.tsx
│ │ ├── Ideas.tsx
│ │ └── KeywordOpportunities.tsx
│ ├── Writer/
│ │ ├── Dashboard.tsx
│ │ ├── Tasks.tsx
│ │ ├── Content.tsx
│ │ ├── ContentView.tsx
│ │ ├── Drafts.tsx
│ │ ├── Images.tsx
│ │ ├── Published.tsx
│ │ └── Review.tsx
│ ├── Linker/
│ │ └── [Linker Pages]
│ ├── Optimizer/
│ │ └── [Optimizer Pages]
│ ├── Settings/
│ │ └── [Settings Pages]
│ └── [Other Modules]
├── components/
│ ├── common/
│ │ ├── Table.tsx
│ │ ├── Modal.tsx
│ │ ├── Form.tsx
│ │ ├── Button.tsx
│ │ └── [Shared UI Components]
│ ├── [Module-Specific Components]
│ └── [Feature Components]
├── api/
│ ├── client.ts # Axios setup
│ ├── auth.ts # Auth API calls
│ ├── planner.ts # Planner endpoints
│ ├── writer.ts # Writer endpoints
│ ├── [module].ts # Module-specific APIs
│ └── hooks/
│ └── useApi.ts # API hook
├── store/
│ ├── authStore.ts # Auth state
│ ├── siteStore.ts # Site/Sector state
│ ├── [module]Store.ts # Module state
│ └── globalStore.ts # Global state
├── hooks/
│ ├── useAuth.ts
│ ├── useApi.ts
│ ├── useSite.ts
│ └── [Custom Hooks]
├── types/
│ ├── api.ts # API type definitions
│ ├── models.ts # Data model types
│ └── [Module Types]
└── utils/
├── formatters.ts
├── validators.ts
└── [Utility Functions]
```
### Feature: Adding a Column to a List/Table
**Module Example: Writer/Tasks List**
#### Files to Modify:
| Layer | File | Change Type | Action |
|-------|------|-------------|--------|
| **Data Type** | `frontend/src/types/models.ts` | Modify | Add field to Task interface |
| **API Response** | `frontend/src/api/writer.ts` | Auto | API will return new field from backend |
| **Page Component** | `frontend/src/pages/Writer/Tasks.tsx` | Modify | Add column to table columns config |
| **Table Component** | `frontend/src/components/Writer/TasksTable.tsx` | Modify | Render new column in JSX |
| **Backend ViewSet** | `backend/igny8_core/modules/writer/views.py` | Modify | Add to `filterset_fields` if filterable, `ordering_fields` if sortable |
| **Backend Serializer** | `backend/igny8_core/modules/writer/serializers.py` | Modify | Add field to serializer `fields` list |
| **Backend Model** | `backend/igny8_core/business/content/models.py` | Modify | Add field to Tasks model class |
| **Backend Migration** | `backend/igny8_core/migrations/` | Create | `python manage.py makemigrations` |
#### Step-by-Step for "Adding 'priority' column to Tasks list":
```python
# Step 1: Backend Model (models.py)
class Tasks(SiteSectorBaseModel):
# ... existing fields ...
priority = models.IntegerField(
choices=[(1, 'Low'), (2, 'Medium'), (3, 'High')],
default=2
)
# Step 2: Backend Serializer (serializers.py)
class TasksSerializer(serializers.ModelSerializer):
class Meta:
model = Tasks
fields = ['id', 'title', 'status', 'priority', ...] # Add 'priority'
# Step 3: Backend ViewSet (views.py) - if filterable/sortable
class TasksViewSet(SiteSectorModelViewSet):
filterset_fields = ['status', 'cluster_id', 'priority'] # Add 'priority'
ordering_fields = ['title', 'created_at', 'priority'] # Add 'priority'
# Step 4: Frontend Type (types/models.ts)
interface Task {
id: number;
title: string;
status: string;
priority: number; // Add this
// ... other fields
}
# Step 5: Frontend API (api/writer.ts) - No changes needed if using generic fetch
# Step 6: Frontend Component (pages/Writer/Tasks.tsx)
const columns = [
{ key: 'id', label: 'ID', width: '10%' },
{ key: 'title', label: 'Title', width: '40%' },
{ key: 'status', label: 'Status', width: '20%' },
{ key: 'priority', label: 'Priority', width: '15%' }, // Add this
];
# Step 7: Database Migration
# bash: python manage.py makemigrations
# bash: python manage.py migrate
```
### Feature: Adding a Form Field
**Module Example: Writer/Tasks Create Form**
#### Files to Modify:
| Layer | File | Change Type | Description |
|-------|------|-------------|-------------|
| **Backend Model** | `backend/.../models.py` | Add | New model field with validators |
| **Backend Serializer** | `backend/.../serializers.py` | Add | Serializer field with validation |
| **Backend ViewSet** | `backend/.../views.py` | Modify | Add to `filterset_fields` if needed |
| **Frontend Type** | `frontend/src/types/models.ts` | Add | Add to interface |
| **Frontend Form Component** | `frontend/src/pages/Writer/[FormPage].tsx` | Add | Add form input JSX |
| **Frontend Validation** | `frontend/src/utils/validators.ts` | Add | Client-side validation rule |
| **Frontend State** | `frontend/src/store/[module]Store.ts` | Add | Add to form state if needed |
| **Database Migration** | `backend/migrations/` | Create | If model field is added |
#### Example: "Adding 'estimatedWordCount' field to Tasks form":
```python
# Step 1: Backend Model
class Tasks(SiteSectorBaseModel):
# ... existing fields ...
word_count = models.IntegerField(
default=1000,
validators=[MinValueValidator(100), MaxValueValidator(10000)],
help_text="Target word count (100-10000)"
)
# Step 2: Backend Serializer
class TasksSerializer(serializers.ModelSerializer):
word_count = serializers.IntegerField(
required=False,
min_value=100,
max_value=10000
)
class Meta:
model = Tasks
fields = [..., 'word_count']
# Step 3: Frontend Type
interface Task {
id: number;
title: string;
wordCount: number; // Add this (camelCase)
}
# Step 4: Frontend Form Component
function TaskForm() {
const [formData, setFormData] = useState({
title: '',
wordCount: 1000, // Add this
});
return (
<form>
{/* ... other fields ... */}
<input
type="number"
name="wordCount"
label="Word Count"
min={100}
max={10000}
value={formData.wordCount}
onChange={e => setFormData({...formData, wordCount: e.target.value})}
/>
</form>
);
}
# Step 5: Frontend Validation
export const validateTaskForm = (data) => {
if (data.wordCount < 100 || data.wordCount > 10000) {
return 'Word count must be between 100 and 10000';
}
return null;
};
```
### Feature: Adding a New Page/View
**Module Example: Adding "Writer/Scheduled" Page**
#### Files to Create/Modify:
| Layer | File | Change Type | Action |
|-------|------|-------------|--------|
| **New Page Component** | `frontend/src/pages/Writer/Scheduled.tsx` | Create | New React component |
| **Page Router** | `frontend/src/App.tsx` | Modify | Add route entry |
| **Navigation** | `frontend/src/layout/Sidebar.tsx` | Modify | Add menu item |
| **API Hooks** | `frontend/src/api/writer.ts` | Modify | Add API call if needed |
| **Type Definitions** | `frontend/src/types/models.ts` | Modify | Add types if needed |
#### Step-by-Step for "Adding Writer/Scheduled Page":
```typescript
// Step 1: Create new page component
// File: frontend/src/pages/Writer/Scheduled.tsx
import React, { useEffect, useState } from 'react';
import { getScheduledContent } from '../../api/writer';
import ContentTable from '../../components/Writer/ContentTable';
export default function ScheduledPage() {
const [content, setContent] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
const loadContent = async () => {
try {
const response = await getScheduledContent({
siteId: currentSite.id,
sectorId: currentSector.id,
status: 'scheduled'
});
setContent(response.data);
} catch (error) {
console.error('Failed to load scheduled content:', error);
} finally {
setLoading(false);
}
};
loadContent();
}, []);
return (
<div className="p-6">
<h1 className="text-2xl font-bold mb-6">Scheduled Content</h1>
<ContentTable content={content} loading={loading} />
</div>
);
}
// Step 2: Add route in App.tsx
import ScheduledPage from './pages/Writer/Scheduled';
function App() {
return (
<Routes>
{/* ... other routes ... */}
<Route path="/writer/scheduled" element={<ScheduledPage />} />
</Routes>
);
}
// Step 3: Add to Sidebar navigation
// File: frontend/src/layout/Sidebar.tsx
<NavItem
to="/writer/scheduled"
label="Scheduled"
icon={<CalendarIcon />}
/>
// Step 4: Add API function if needed
// File: frontend/src/api/writer.ts
export const getScheduledContent = async (params) => {
return fetchAPI('/api/v1/writer/content/', {
query: { ...params, status: 'scheduled' }
});
};
```
### Feature: Adding a Filter/Search
**Module Example: Adding "Priority Filter" to Tasks**
#### Files to Modify:
| Layer | File | Change Type | Description |
|-------|------|-------------|-------------|
| **Backend ViewSet** | `backend/.../views.py` | Modify | Add to `filterset_fields` |
| **Backend Model** | `backend/.../models.py` | Check | Field must have choices |
| **Frontend Filter UI** | `frontend/src/components/Writer/TasksFilter.tsx` | Add | Add filter control |
| **Frontend State** | `frontend/src/store/writerStore.ts` | Modify | Add filter state |
#### Example:
```python
# Backend (views.py)
class TasksViewSet(SiteSectorModelViewSet):
filterset_fields = ['status', 'cluster_id', 'priority'] # Add 'priority'
# Frontend - Add Filter Component
interface TaskFilter {
priority?: number;
status?: string;
}
function TasksFilter() {
const [filters, setFilters] = useState<TaskFilter>({});
return (
<div className="flex gap-4 mb-6">
<select
value={filters.priority || ''}
onChange={(e) => setFilters({...filters, priority: e.target.value})}
>
<option value="">All Priorities</option>
<option value="1">Low</option>
<option value="2">Medium</option>
<option value="3">High</option>
</select>
</div>
);
}
```
---
## Backend Feature Modifications
### Directory Structure
```
backend/igny8_core/
├── modules/ # API ViewSets (REST endpoints)
│ ├── planner/
│ │ ├── views.py # ViewSets
│ │ ├── serializers.py # Serializers
│ │ ├── urls.py # Route definitions
│ │ └── apps.py
│ ├── writer/
│ │ ├── views.py
│ │ ├── serializers.py
│ │ ├── urls.py
│ │ └── apps.py
│ ├── [other modules]
│ └── urls.py # Root routing
├── business/ # Business logic & models
│ ├── planning/
│ │ ├── models.py # Database models
│ │ └── services/ # Business logic
│ ├── content/
│ │ ├── models.py
│ │ └── services/
│ ├── [other domains]
│ └── models.py
├── auth/
│ ├── models.py # User, Account, Site, Sector
│ ├── views.py
│ ├── serializers.py
│ └── urls.py
├── api/
│ ├── base.py # Base ViewSet classes
│ ├── response.py # Response utilities
│ ├── pagination.py
│ ├── permissions.py
│ ├── throttles.py
│ └── exception_handlers.py
├── ai/ # AI Engine
│ ├── engine.py
│ ├── ai_core.py
│ ├── registry.py
│ └── functions/
├── middleware/
├── utils/
├── tasks/ # Celery tasks
├── migrations/ # Database migrations
├── settings.py # Django settings
├── urls.py # Root URL config
└── wsgi.py
```
### Feature: Adding an API Endpoint
**Module Example: Adding "GET /writer/tasks/{id}/brief/" endpoint**
#### Files to Create/Modify:
| File | Change Type | Description |
|------|-------------|-------------|
| `backend/igny8_core/modules/writer/views.py` | Add | Add `@action` method to ViewSet |
| `backend/igny8_core/modules/writer/serializers.py` | Check | Serializer for response |
| `backend/igny8_core/modules/writer/urls.py` | Auto | Routes auto-generated by DRF `DefaultRouter` |
#### Step-by-Step Example:
```python
# Step 1: Add action to ViewSet (views.py)
class TasksViewSet(SiteSectorModelViewSet):
# ... existing code ...
@action(detail=True, methods=['get'])
def brief(self, request, pk=None):
"""
Get task brief
GET /api/v1/writer/tasks/{id}/brief/
"""
task = self.get_object()
# Business logic to generate brief
brief_data = {
'task_id': task.id,
'title': task.title,
'keywords': task.keywords,
'cluster': task.cluster.name if task.cluster else None,
'description': task.description
}
return success_response(
success=True,
data=brief_data,
message='Task brief retrieved'
)
# Step 2: That's it! DRF auto-generates the route
# URL will be: /api/v1/writer/tasks/123/brief/
# Method: GET
# Response format: { success: true, data: {...}, message: '...' }
# Step 3: Frontend API hook
// frontend/src/api/writer.ts
export const getTaskBrief = async (taskId: number) => {
return fetchAPI(`/api/v1/writer/tasks/${taskId}/brief/`);
};
```
### Feature: Adding a Status/Choice Field
**Module Example: Adding "priority" choice field to Tasks**
#### Files to Modify:
| Layer | File | Change Type | Action |
|-------|------|-------------|--------|
| **Backend Model** | `backend/.../models.py` | Add | Add field with CHOICES |
| **Database Migration** | `backend/migrations/` | Create | Auto from model |
| **Backend Serializer** | `backend/.../serializers.py` | Auto | Choices auto-included |
| **Backend ViewSet** | `backend/.../views.py` | Modify | Add to filters if needed |
| **Frontend Types** | `frontend/src/types/models.ts` | Add | Add type definition |
| **Frontend Enum/Constant** | `frontend/src/config/constants.ts` | Add | Add choice options |
| **Frontend UI** | Components using field | Use | Render as select/dropdown |
#### Example:
```python
# Step 1: Backend Model (models.py)
class Tasks(SiteSectorBaseModel):
PRIORITY_CHOICES = [
(1, 'Low'),
(2, 'Medium'),
(3, 'High'),
(4, 'Urgent'),
]
priority = models.IntegerField(
choices=PRIORITY_CHOICES,
default=2,
help_text="Task priority level"
)
# Step 2: Backend Serializer (serializers.py) - No changes needed!
# DRF automatically includes choices in API response as:
# {
# "priority": 2,
# "priority_display": "Medium",
# "priority_choices": [[1, "Low"], [2, "Medium"], ...]
# }
# Step 3: Frontend Constant (config/constants.ts)
export const TASK_PRIORITIES = {
LOW: 1,
MEDIUM: 2,
HIGH: 3,
URGENT: 4,
};
export const TASK_PRIORITY_LABELS = {
1: 'Low',
2: 'Medium',
3: 'High',
4: 'Urgent',
};
# Step 4: Frontend Type (types/models.ts)
interface Task {
id: number;
priority: 1 | 2 | 3 | 4; // Use enum values
}
# Step 5: Frontend Component
function TaskSelect() {
return (
<select value={task.priority}>
<option value={1}>Low</option>
<option value={2}>Medium</option>
<option value={3}>High</option>
<option value={4}>Urgent</option>
</select>
);
}
```
### Feature: Adding Validation
**Module Example: Validating task word count (100-10000)**
#### Files to Create/Modify:
| File | Change Type | Description |
|------|-------------|-------------|
| `backend/igny8_core/business/content/services/validation_service.py` | Create | Validation logic |
| `backend/igny8_core/modules/writer/serializers.py` | Modify | Add field validation |
| `frontend/src/utils/validators.ts` | Add | Client-side validation |
#### Example:
```python
# Step 1: Backend Model Field Validators (models.py)
from django.core.validators import MinValueValidator, MaxValueValidator
class Tasks(SiteSectorBaseModel):
word_count = models.IntegerField(
default=1000,
validators=[
MinValueValidator(100, message="Minimum word count is 100"),
MaxValueValidator(10000, message="Maximum word count is 10000")
]
)
# Step 2: Backend Serializer Validation (serializers.py)
class TasksSerializer(serializers.ModelSerializer):
word_count = serializers.IntegerField(
min_value=100,
max_value=10000,
required=False
)
def validate_word_count(self, value):
if value and (value < 100 or value > 10000):
raise serializers.ValidationError(
"Word count must be between 100 and 10000"
)
return value
class Meta:
model = Tasks
fields = ['id', 'title', 'word_count', ...]
# Step 3: Frontend Validation (utils/validators.ts)
export const validateTaskWordCount = (wordCount: number): string | null => {
if (wordCount < 100) {
return 'Word count must be at least 100';
}
if (wordCount > 10000) {
return 'Word count cannot exceed 10000';
}
return null;
};
# Step 4: Frontend Component
function TaskForm() {
const [wordCount, setWordCount] = useState(1000);
const [error, setError] = useState('');
const handleChange = (value) => {
setWordCount(value);
const err = validateTaskWordCount(value);
setError(err || '');
};
return (
<>
<input
type="number"
value={wordCount}
onChange={(e) => handleChange(Number(e.target.value))}
/>
{error && <span className="text-red-500">{error}</span>}
</>
);
}
```
### Feature: Adding a Background Task (Celery)
**Module Example: Adding "Async content generation" task**
#### Files to Create/Modify:
| File | Change Type | Description |
|------|-------------|-------------|
| `backend/igny8_core/tasks/[domain]_tasks.py` | Create | Celery task function |
| `backend/igny8_core/modules/[module]/views.py` | Modify | Queue task from ViewSet |
| `backend/igny8_core/settings.py` | Check | Celery config (usually pre-configured) |
#### Example: Adding "generate_content_images" async task
```python
# Step 1: Create Celery Task (tasks/writer_tasks.py)
from celery import shared_task
import logging
logger = logging.getLogger(__name__)
@shared_task(bind=True, max_retries=3)
def generate_content_images(self, content_id):
"""
Generate AI images for content
"""
from igny8_core.business.content.models import Content
from igny8_core.ai.engine import AIEngine
logger.info(f"[generate_content_images] 🎬 Starting image generation for content {content_id}")
try:
content = Content.objects.get(id=content_id)
# Generate images
engine = AIEngine()
images = engine.generate_images(
content_id=content.id,
title=content.title,
keywords=content.secondary_keywords
)
# Save images
for image_data in images:
Image.objects.create(
content=content,
url=image_data['url'],
prompt=image_data['prompt']
)
logger.info(f"[generate_content_images] ✅ Successfully generated {len(images)} images")
return {'success': True, 'image_count': len(images)}
except Content.DoesNotExist:
logger.error(f"[generate_content_images] ❌ Content {content_id} not found")
return {'success': False, 'error': 'Content not found'}
except Exception as exc:
logger.error(f"[generate_content_images] ❌ Task failed: {str(exc)}")
# Retry with exponential backoff
raise self.retry(exc=exc, countdown=2 ** self.request.retries)
# Step 2: Queue task from ViewSet (views.py)
class ContentViewSet(SiteSectorModelViewSet):
@action(detail=True, methods=['post'])
def generate_images(self, request, pk=None):
"""
Trigger async image generation
POST /api/v1/writer/content/{id}/generate_images/
"""
content = self.get_object()
# Queue background task
from igny8_core.tasks.writer_tasks import generate_content_images
task = generate_content_images.delay(content.id)
return success_response(
success=True,
data={'task_id': task.id},
message='Image generation started'
)
# Step 3: Frontend to trigger task
// frontend/src/api/writer.ts
export const generateContentImages = async (contentId: number) => {
return fetchAPI(`/api/v1/writer/content/${contentId}/generate_images/`, {
method: 'POST'
});
};
// frontend/src/pages/Writer/Content.tsx
async function handleGenerateImages(contentId) {
try {
const response = await generateContentImages(contentId);
toast.success('Image generation started');
} catch (error) {
toast.error('Failed to start image generation');
}
}
```
---
## Database Schema Changes
### Feature: Adding/Modifying a Database Column
#### Complete Workflow:
```bash
# Step 1: Add field to model
# File: backend/igny8_core/business/content/models.py
class Content(SiteSectorBaseModel):
# ... existing fields ...
seo_score = models.IntegerField(
default=0,
validators=[MinValueValidator(0), MaxValueValidator(100)],
help_text="SEO optimization score (0-100)"
)
# Step 2: Create migration
$ python manage.py makemigrations writer
# Output: Migrations for 'writer':
# migrations/0015_content_seo_score.py
# Step 3: Review migration (optional)
$ cat migrations/0015_content_seo_score.py
# Step 4: Apply migration
$ python manage.py migrate
# Step 5: Update serializer to include new field
# File: backend/igny8_core/modules/writer/serializers.py
class ContentSerializer(serializers.ModelSerializer):
class Meta:
model = Content
fields = [
'id', 'title', 'content_html', 'status',
'seo_score', # Add this
# ... other fields ...
]
# Step 6: Update frontend types
// frontend/src/types/models.ts
interface Content {
id: number;
title: string;
contentHtml: string;
seoScore: number; // Add this
}
# Step 7: Update components to use new field
```
### Feature: Removing a Database Column
```python
# Step 1: Create migration to remove field
$ python manage.py makemigrations writer --remove-field
# Step 2: Or manually edit model - comment out field
class Content(SiteSectorBaseModel):
# ... existing fields ...
# seo_score = models.IntegerField(...) # REMOVED
# Step 3: Auto-create migration
$ python manage.py makemigrations writer
# Step 4: Apply migration
$ python manage.py migrate
# Step 5: Remove from serializer
# backend/igny8_core/modules/writer/serializers.py
# Remove 'seo_score' from fields list
# Step 6: Remove from frontend types and components
```
### Feature: Modifying a Database Column
```python
# Example: Change word_count max value from 10000 to 20000
# Step 1: Update model
class Tasks(SiteSectorBaseModel):
word_count = models.IntegerField(
default=1000,
validators=[MinValueValidator(100), MaxValueValidator(20000)] # Changed
)
# Step 2: Create migration
$ python manage.py makemigrations writer
# Step 3: Apply migration
$ python manage.py migrate
# Step 4: Update serializer if validation changed
class TasksSerializer(serializers.ModelSerializer):
word_count = serializers.IntegerField(
min_value=100,
max_value=20000 # Update
)
# Step 5: Update frontend validation constants
export const MAX_WORD_COUNT = 20000; // Update
```
---
## Cross-Module Modifications
### Feature: Adding a Relationship Between Modules
**Example: Link Content to Ideas (Writer → Planner)**
#### Files to Modify:
```python
# Step 1: Backend Model - Add ForeignKey
# backend/igny8_core/business/content/models.py
class Content(SiteSectorBaseModel):
# ... existing fields ...
idea = models.ForeignKey(
'planner.ContentIdeas',
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name='contents',
help_text="Source content idea"
)
# Step 2: Create migration
$ python manage.py makemigrations writer
# Step 3: Apply migration
$ python manage.py migrate
# Step 4: Update serializer to include nested relationship
# backend/igny8_core/modules/writer/serializers.py
from igny8_core.modules.planner.serializers import ContentIdeasSerializer
class ContentSerializer(serializers.ModelSerializer):
idea = ContentIdeasSerializer(read_only=True)
idea_id = serializers.PrimaryKeyRelatedField(
queryset=ContentIdeas.objects.all(),
source='idea',
write_only=True
)
class Meta:
model = Content
fields = ['id', 'title', 'idea', 'idea_id', ...]
# Step 5: Update ViewSet to support filtering by idea
# backend/igny8_core/modules/writer/views.py
class ContentViewSet(SiteSectorModelViewSet):
filterset_fields = ['status', 'cluster_id', 'idea_id'] # Add idea_id
ordering_fields = ['title', 'created_at', 'idea_id'] # Add idea_id
# Step 6: Frontend - Update type
// frontend/src/types/models.ts
interface Content {
id: number;
title: string;
idea?: Idea; // Add nested object
ideaId?: number; // Add ID for create/update
}
# Step 7: Frontend - Display related idea
// frontend/src/pages/Writer/Content.tsx
{content.idea && (
<div>Idea: {content.idea.ideaTitle}</div>
)}
```
---
## Common Workflow Patterns
### Pattern 1: Adding a Simple Field to List Page
**Timeline: ~15 minutes**
```
1. Backend Model → Add field with validators
2. DB Migration → makemigrations + migrate
3. Backend Serializer → Add to fields list
4. Backend ViewSet → Add to filters/ordering if needed
5. Frontend Type → Add to interface
6. Frontend Component → Add to table columns
7. Test → Verify in both UI and API
```
**Files Modified:**
- `backend/igny8_core/business/*/models.py`
- `backend/igny8_core/migrations/XXXX_*.py`
- `backend/igny8_core/modules/*/serializers.py`
- `backend/igny8_core/modules/*/views.py`
- `frontend/src/types/models.ts`
- `frontend/src/pages/*/[Page].tsx`
### Pattern 2: Adding a New Feature Page
**Timeline: ~1 hour**
```
1. Backend ViewSet/Action → Create endpoint
2. Backend Serializer → Define response format
3. Frontend API Hook → Create fetch function
4. Frontend Type → Define data interface
5. Frontend Page Component → Create page
6. Frontend Router → Add route
7. Frontend Navigation → Add menu item
8. Test → End-to-end flow
```
**Files Modified:**
- `backend/igny8_core/modules/*/views.py`
- `backend/igny8_core/modules/*/serializers.py`
- `frontend/src/api/*.ts`
- `frontend/src/types/models.ts`
- `frontend/src/pages/*/*.tsx`
- `frontend/src/App.tsx`
- `frontend/src/layout/Sidebar.tsx`
### Pattern 3: Adding Async Processing
**Timeline: ~30 minutes**
```
1. Backend Celery Task → Create task function
2. Backend ViewSet Action → Queue task from endpoint
3. Frontend API Hook → Create trigger function
4. Frontend Component → Add button to trigger
5. Frontend Polling/Polling → Show task status
6. Test → Verify task execution and completion
```
**Files Modified:**
- `backend/igny8_core/tasks/*_tasks.py`
- `backend/igny8_core/modules/*/views.py`
- `frontend/src/api/*.ts`
- `frontend/src/pages/*/*.tsx`
---
## File Organization Index
### Module File Structure Template
For each module (Planner, Writer, Linker, etc.):
```
backend/igny8_core/
├── modules/[module]/
│ ├── views.py # ViewSets, @actions
│ ├── serializers.py # Serializers
│ ├── urls.py # Route registration
│ └── apps.py
└── business/[domain]/
├── models.py # Data models
├── services/
│ ├── service1.py # Business logic
│ └── service2.py
└── migrations/
└── XXXX_*.py # DB migrations
frontend/src/
├── pages/[Module]/
│ ├── Dashboard.tsx # Overview page
│ ├── [Feature].tsx # Feature pages
│ └── [Detail].tsx # Detail views
├── components/[Module]/
│ ├── [Feature]Table.tsx # Table components
│ ├── [Feature]Form.tsx # Form components
│ └── [Feature]Filter.tsx # Filter components
├── api/
│ └── [module].ts # API calls
├── store/
│ └── [module]Store.ts # State management
└── types/
└── models.ts # Type definitions
```
### Global Files (All Modules)
| File | Purpose | Where Located |
|------|---------|---------------|
| **API Base Classes** | ViewSet, Serializer base | `backend/igny8_core/api/base.py` |
| **Response Format** | Unified responses | `backend/igny8_core/api/response.py` |
| **Permissions** | Role-based access | `backend/igny8_core/api/permissions.py` |
| **Pagination** | List pagination | `backend/igny8_core/api/pagination.py` |
| **Root Router** | Route registration | `backend/igny8_core/urls.py` |
| **Settings** | Django config | `backend/igny8_core/settings.py` |
| **Auth Models** | User, Site, Sector | `backend/igny8_core/auth/models.py` |
| **API Client** | Frontend HTTP | `frontend/src/api/client.ts` |
| **Auth Store** | User state | `frontend/src/store/authStore.ts` |
| **Site Store** | Site/Sector context | `frontend/src/store/siteStore.ts` |
| **App Router** | Frontend routes | `frontend/src/App.tsx` |
| **Sidebar** | Navigation menu | `frontend/src/layout/Sidebar.tsx` |
| **Constants** | Global constants | `frontend/src/config/constants.ts` |
| **Validators** | Validation rules | `frontend/src/utils/validators.ts` |
---
## Quick Checklists
### Adding a New Column: Checklist
- [ ] Add field to Backend Model (`models.py`)
- [ ] Run `makemigrations`
- [ ] Run `migrate`
- [ ] Add field to Backend Serializer (`serializers.py`)
- [ ] Add to ViewSet `filterset_fields` if filterable
- [ ] Add to ViewSet `ordering_fields` if sortable
- [ ] Add to Frontend Type (`types/models.ts`)
- [ ] Add to Frontend Component columns config
- [ ] Add to Frontend Table JSX rendering
- [ ] Test API response includes field
- [ ] Test frontend displays column
- [ ] Test filter/sort works (if applicable)
### Adding a New Page: Checklist
- [ ] Create new Page component (`pages/[Module]/[Page].tsx`)
- [ ] Create or update API hook (`api/[module].ts`)
- [ ] Add route to router (`App.tsx`)
- [ ] Add menu item to navigation (`layout/Sidebar.tsx`)
- [ ] Add types if needed (`types/models.ts`)
- [ ] Test page loads
- [ ] Test data fetches
- [ ] Test filters/search work
- [ ] Test pagination works
- [ ] Test error states
### Adding an API Endpoint: Checklist
- [ ] Define endpoint action in ViewSet (`views.py`)
- [ ] Use `@action(detail=...)` decorator
- [ ] Define response format using serializer
- [ ] Add permission check if needed
- [ ] Document docstring
- [ ] Test endpoint with API client
- [ ] Verify unified response format
- [ ] Create frontend API hook (`api/[module].ts`)
- [ ] Test from frontend component
- [ ] Verify error handling
---
**End of Document**
For questions on specific features, refer to:
- Architecture: `00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md`
- API Details: `01-IGNY8-REST-API-COMPLETE-REFERENCE.md`
- Workflows: `02-PLANNER-WRITER-WORKFLOW-TECHNICAL-GUIDE.md`
Reference in New Issue View Git Blame Copy Permalink