salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
alorig
2025-11-24 07:18:15 +05:00
parent f255e3c0a0
commit af6b29b8f8
13 changed files with 2003 additions and 8376 deletions
Download Patch File Download Diff File Expand all files Collapse all files

810
CHANGELOG.md
View File

@@ -1,8 +1,9 @@
# IGNY8 Changelog
# Changelog
**Current Version:** `1.0.0`
**Last Updated:** 2025-01-XX
**Purpose:** Complete changelog of all changes, fixes, and features. Only updated after user confirmation.
All notable changes to the IGNY8 platform will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
---
@@ -10,8 +11,6 @@
**IMPORTANT**: This changelog is only updated after user confirmation that a fix or feature is complete and working.
**For AI Agents**: Read `docs/00-DOCUMENTATION-MANAGEMENT.md` before making any changes to this file.
### Changelog Structure
Each entry follows this format:
@@ -20,579 +19,340 @@ Each entry follows this format:
- **Type**: Added, Changed, Fixed, Deprecated, Removed, Security
- **Description**: Clear description of the change
- **Affected Areas**: Modules, components, or features affected
- **Documentation**: Reference to updated documentation files
---
## [Unreleased]
### Added
- **Planning Documents Organization**: Organized architecture and implementation planning documents
- Created `docs/planning/` directory for all planning documents
- Moved `IGNY8-HOLISTIC-ARCHITECTURE-PLAN.md` to `docs/planning/`
- Moved `IGNY8-IMPLEMENTATION-PLAN.md` to `docs/planning/`
- Moved `Igny8-phase-2-plan.md` to `docs/planning/`
- Moved `CONTENT-WORKFLOW-DIAGRAM.md` to `docs/planning/`
- Moved `ARCHITECTURE_CONTEXT.md` to `docs/planning/`
- Moved `sample-usage-limits-credit-system` to `docs/planning/`
- Created `docs/refactor/` directory for refactoring plans
- Updated `README.md` to reflect new document structure
- **Impact**: Better organization of planning documents, easier to find and maintain
### Changed
- **API Documentation Consolidation**: Consolidated all API documentation into single comprehensive reference
- Created `docs/API-COMPLETE-REFERENCE.md` - Unified API documentation covering all endpoints, authentication, response formats, error handling, rate limiting, permissions, and integration examples
- Removed redundant documentation files:
- `docs/API-DOCUMENTATION.md` (consolidated into complete reference)
- `docs/DOCUMENTATION-SUMMARY.md` (consolidated into complete reference)
- `unified-api/API-ENDPOINTS-ANALYSIS.md` (consolidated into complete reference)
- `unified-api/API-STANDARD-v1.0.md` (consolidated into complete reference)
- New unified document includes: complete endpoint reference, authentication guide, response format standards, error handling, rate limiting, pagination, roles & permissions, tenant/site/sector scoping, integration examples (Python, JavaScript, cURL, PHP), testing & debugging, and change management
- **Impact**: Single source of truth for all API documentation, easier to maintain and navigate
### Added
- Unified API Standard v1.0 implementation
- API Monitor page for endpoint health monitoring
- CRUD operations monitoring for Planner and Writer modules
- Sidebar API status indicator for aws-admin accounts
- **Health Check Endpoint**: `GET /api/v1/system/ping/` - Public health check endpoint per API Standard v1.0 requirement
- Returns unified format: `{success: true, data: {status: 'ok'}}`
- Tagged as 'System' in Swagger/ReDoc documentation
- Public endpoint (AllowAny permission)
### Changed
- All API endpoints now return unified response format (`{success, data, message, errors}`)
- Frontend `fetchAPI` wrapper automatically extracts data from unified format
- All error responses follow unified format with `request_id` tracking
- Rate limiting configured with scoped throttles per module
- **Integration Views**: All integration endpoints now use unified response format
- Replaced 40+ raw `Response()` calls with `success_response()`/`error_response()` helpers
- All responses include `request_id` for tracking
- Updated frontend components to handle extracted data format
- **API Documentation**: Updated Swagger/ReDoc description to include all public endpoints
- Added `/api/v1/system/ping/` to public endpoints list
- Updated schema extensions to properly tag ping endpoint
- **AI Framework Refactoring**: Removed hardcoded model defaults, IntegrationSettings is now the single source of truth
- Removed `MODEL_CONFIG` dictionary with hardcoded defaults
- Removed Django settings `DEFAULT_AI_MODEL` fallback
- `get_model_config()` now requires `account` parameter and raises clear errors if IntegrationSettings not configured
- All AI functions now require account-specific model configuration
- Removed orphan code: `get_model()`, `get_max_tokens()`, `get_temperature()` helper functions
- Removed unused exports from `__init__.py`: `register_function`, `list_functions`, `get_model`, `get_max_tokens`, `get_temperature`
- **Impact**: Each account must configure their own AI models in IntegrationSettings
- **Documentation**: See `backend/igny8_core/ai/REFACTORING-IMPLEMENTED.md` for complete details
### Fixed
- Keyword edit form now correctly populates existing values
- Auto-cluster function now works correctly with unified API format
- ResourceDebugOverlay now correctly extracts data from unified API responses
- All frontend pages now correctly handle unified API response format
- **Integration Views**: Fixed all integration endpoints not using unified response format
- `_test_openai()` and `_test_runware()` methods now use unified format
- `generate_image()`, `create()`, `save_settings()` methods now use unified format
- `get_image_generation_settings()` and `task_progress()` methods now use unified format
- All error responses now include `request_id` and follow unified format
- Fixed OpenAI integration endpoint error handling - invalid API keys now return 400 (Bad Request) instead of 401 (Unauthorized)
- **Frontend Components**: Updated to work with unified format
- `ValidationCard.tsx` - Removed dual-format handling, now works with extracted data
- `Integration.tsx` - Simplified to work with unified format
- `ImageGenerationCard.tsx` - Updated to work with extracted data format
- **Frontend Authentication**: Fixed `getAuthToken is not defined` error in `authStore.ts`
- Updated `refreshUser()` to use `fetchAPI()` instead of manual fetch with `getAuthToken()`
- Removed error throwing from catch block to prevent error accumulation
- **Frontend Error Handling**: Fixed console error accumulation
- `ResourceDebugOverlay.tsx` now silently ignores 404 errors for request-metrics endpoint
- Removed error throwing from `refreshUser()` catch block to prevent error spam
- **AI Framework Error Handling**: Improved error messages and exception handling
- `AIEngine._handle_error()` now preserves exception types for better error messages
- All AI function errors now include proper `error_type` (ConfigurationError, AccountNotFound, etc.)
- Fixed "Task failed - exception details unavailable" by improving error type preservation
- Error messages now clearly indicate when IntegrationSettings are missing or misconfigured
---
## [1.1.1] - 2025-01-XX
### Security
- **CRITICAL**: Fixed `AIPromptViewSet` security vulnerability - changed from `permission_classes = []` (allowing unauthenticated access) to `IsAuthenticatedAndActive + HasTenantAccess`
- Added `IsEditorOrAbove` permission check for `save_prompt` and `reset_prompt` actions in `AIPromptViewSet`
- All billing ViewSets now require `IsAuthenticatedAndActive + HasTenantAccess` for proper tenant isolation
- `CreditTransactionViewSet` now requires `IsAdminOrOwner` per API Standard v1.0 (billing/transactions require admin/owner)
- All system settings ViewSets now use standard permissions (`IsAuthenticatedAndActive + HasTenantAccess`)
- All auth ViewSets now explicitly include `IsAuthenticatedAndActive + HasTenantAccess` for proper tenant isolation
### Changed
- **Auth Endpoints**: All authentication endpoints (`RegisterView`, `LoginView`, `ChangePasswordView`, `MeView`) now use unified response format with `success_response()` and `error_response()` helpers
- All responses now include `request_id` for error tracking
- Error responses follow unified format with `error` and `errors` fields
- Success responses follow unified format with `success`, `data`, and `message` fields
- **Billing Module**: Refactored `CreditUsageViewSet` and `CreditTransactionViewSet` to inherit from `AccountModelViewSet` instead of manual account filtering
- Account filtering now handled automatically by base class
- Improved code maintainability and consistency
- **System Settings**: All 5 system settings ViewSets now use standard permission classes
- `SystemSettingsViewSet`, `AccountSettingsViewSet`, `UserSettingsViewSet`, `ModuleSettingsViewSet`, `AISettingsViewSet`
- Write operations require `IsAdminOrOwner` per standard
- **Integration Settings**: Added `HasTenantAccess` permission to `IntegrationSettingsViewSet` for proper tenant isolation
- **Auth ViewSets**: Added explicit standard permissions to all auth ViewSets
- `UsersViewSet`, `AccountsViewSet`, `SubscriptionsViewSet`, `SiteUserAccessViewSet` now include `IsAuthenticatedAndActive + HasTenantAccess`
- `SiteViewSet`, `SectorViewSet` now include `IsAuthenticatedAndActive + HasTenantAccess`
### Fixed
- Fixed auth endpoints not returning unified format (were using raw `Response()` instead of helpers)
- Fixed missing `request_id` in auth endpoint responses
- Fixed inconsistent error response format in auth endpoints
- Fixed billing ViewSets not using base classes (manual account filtering replaced with `AccountModelViewSet`)
- Fixed all ViewSets missing standard permissions (`IsAuthenticatedAndActive + HasTenantAccess`)
### Documentation
- Updated implementation plan to reflect completion of all remaining API Standard v1.0 items
- All 8 remaining items from audit completed (100% compliance achieved)
- **API Standard v1.0**: Full compliance achieved
- All 10 audit tasks completed and verified
- All custom @action methods use unified response format
- All ViewSets use proper base classes, pagination, throttles, and permissions
- All error responses include `request_id` tracking
- No raw `Response()` calls remaining (except file downloads)
- All endpoints documented in Swagger/ReDoc with proper tags
---
## [1.1.0] - 2025-01-XX
## [1.0.0] - 2025-11-24
### Added
#### Unified API Standard v1.0
- **Response Format Standardization**
- All endpoints return unified format: `{success: true/false, data: {...}, message: "...", errors: {...}}`
- Paginated responses include `success`, `count`, `next`, `previous`, `results`
- Error responses include `success: false`, `error`, `errors`, `request_id`
- Response helper functions: `success_response()`, `error_response()`, `paginated_response()`
#### Backend Core
- **Multi-Tenancy System**
- Complete account isolation with Account → Site → Sector hierarchy
- User roles: Developer, Owner, Admin, Editor, Viewer, System Bot
- Automatic account filtering via `AccountContextMiddleware`
- Base classes: `AccountModelViewSet` and `SiteSectorModelViewSet`
- Account isolation at database level with ForeignKey relationships
- **Custom Exception Handler**
- Centralized exception handling in `backend/igny8_core/api/exception_handlers.py`
- All exceptions wrapped in unified format
- Proper HTTP status code mapping (400, 401, 403, 404, 409, 422, 429, 500)
- Debug information included in development mode
- **Authentication & Authorization**
- JWT token authentication with PyJWT 2.8+
- 15-minute access token expiry
- Refresh token support
- API key authentication for WordPress integration
- Permission classes: `IsAuthenticatedAndActive`, `HasTenantAccess`, `IsEditorOrAbove`, `IsAdminOrOwner`
- Role-based access control matrix
- **Custom Pagination**
- `CustomPageNumberPagination` class with unified format support
- Default page size: 10, max: 100
- Dynamic page size via `page_size` query parameter
- Includes `success` field in paginated responses
- **Planner Module** (`modules/planner/`)
- Keywords model with search volume, difficulty, intent tracking
- Clusters model with many-to-many keyword relationships
- ContentIdeas model linked to clusters
- AI-powered keyword clustering via `auto_cluster` function
- AI-powered content idea generation via `generate_ideas` function
- Bulk keyword import (CSV and manual)
- ViewSets: `KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet`
- **Base ViewSets**
- `AccountModelViewSet` - Handles account isolation and unified CRUD responses
- `SiteSectorModelViewSet` - Extends account isolation with site/sector filtering
- All CRUD operations (create, retrieve, update, destroy) return unified format
- **Writer Module** (`modules/writer/`)
- Tasks model for content creation workflow
- Content model with HTML/plain text support and unified taxonomy structure
- Images model with featured/in-article image support
- AI content generation via GPT-4 (`generate_content` function)
- AI image generation via DALL-E 3 and Runware (`generate_images` function)
- Content taxonomies (`ContentTaxonomy`) and attributes (unified JSON structure)
- ViewSets: `TasksViewSet`, `ContentViewSet`, `ImagesViewSet`, `ContentTaxonomyViewSet`, `ContentAttributeViewSet`
- **Rate Limiting**
- `DebugScopedRateThrottle` with debug bypass for development
- Scoped rate limits per module (planner, writer, system, billing, auth)
- AI function rate limits (10/min for expensive operations)
- Bypass for aws-admin accounts and admin/developer roles
- Rate limit headers: `X-Throttle-Limit`, `X-Throttle-Remaining`, `X-Throttle-Reset`
- **Linker Module** (`modules/linker/`)
- Internal linking recommendations
- Link graph analysis
- `LinkerViewSet` for link operations
- **Request ID Tracking**
- `RequestIDMiddleware` generates unique UUID for each request
- Request ID included in all error responses
- Request ID in response headers: `X-Request-ID`
- Used for log correlation and debugging
- **Optimizer Module** (`modules/optimizer/`)
- Content quality scoring
- SEO optimization suggestions
- `OptimizerViewSet` for optimization operations
- **API Monitor**
- New page: `/settings/api-monitor` for endpoint health monitoring
- Monitors API status (HTTP response) and data status (page population)
- Endpoint groups: Core Health, Auth, Planner, Writer, System, Billing, CRUD Operations
- Sorting by status (errors first, then warnings, then healthy)
- Real-time endpoint health checks with configurable refresh interval
- Only accessible to aws-admin accounts
- **Publisher Module** (`modules/publisher/`)
- Publishing records tracking (`PublishingRecord` model)
- Deployment records (`DeploymentRecord` model)
- `PublisherViewSet`, `PublishingRecordViewSet`, `DeploymentRecordViewSet`
- **Sidebar API Status Indicator**
- Visual indicator circles for each endpoint group
- Color-coded status (green = healthy, yellow = warning)
- Abbreviations: CO, AU, PM, WM, PC, WC, SY
- Only visible and active for aws-admin accounts on API monitor page
- Prevents console errors on other pages
- **Site Builder Module** (`modules/site_builder/`)
- Site blueprint management (`SiteBlueprint` model)
- Page blueprint creation (`PageBlueprint` model)
- Site structure planning with clusters and taxonomies
- `SiteBlueprintViewSet`, `PageBlueprintViewSet`, `SiteAssetView`, `SiteBuilderMetadataView`
### Changed
- **Automation Module** (`modules/automation/`)
- Automation rules engine (`AutomationRule` model)
- Scheduled tasks (`ScheduledTask` model)
- Rule execution via Celery beat
- `AutomationRuleViewSet`, `ScheduledTaskViewSet`
#### Backend Refactoring
- **Planner Module** - All ViewSets refactored to unified format
- `KeywordViewSet` - CRUD + `auto_cluster` action
- `ClusterViewSet` - CRUD + `auto_generate_ideas` action
- `ContentIdeasViewSet` - CRUD + `bulk_queue_to_writer` action
- **Integration Module** (`modules/integration/`)
- WordPress integration support via `SiteIntegration` model
- Connection testing: `POST /integrations/test-connection/`
- Structure update: `POST /integrations/{id}/update-structure/`
- Content type summary: `GET /integrations/{id}/content-types/`
- Bidirectional sync support with sync status and logs
- Integration services: `IntegrationService`, `SyncService`, `ContentSyncService`, `SyncHealthService`
- Site-level sync endpoints: `/sites/{id}/sync/status/`, `/sites/{id}/sync/run/`
- `IntegrationViewSet` with comprehensive sync management
- **Writer Module** - All ViewSets refactored to unified format
- `TasksViewSet` - CRUD + `auto_generate_content` action
- `ContentViewSet` - CRUD + `generate_image_prompts` action
- `ImagesViewSet` - CRUD + `generate_images` action
- **System Module** (`modules/system/`)
- AI prompt management (`AIPrompt` model with types: cluster, ideas, content, image_prompts)
- Integration settings (`IntegrationSettings` model for OpenAI/Runware config)
- Author profiles for content style (`AuthorProfile` model)
- Content strategies (`Strategy` model)
- System and account settings endpoints
- ViewSets: `AIPromptViewSet`, `AuthorProfileViewSet`, `StrategyViewSet`
- Settings ViewSets: `SystemSettingsViewSet`, `AccountSettingsViewSet`, `UserSettingsViewSet`, `ModuleSettingsViewSet`, `AISettingsViewSet`
- **System Module** - All ViewSets refactored to unified format
- `AIPromptViewSet` - CRUD + `get_by_type`, `save_prompt`, `reset_prompt` actions
- `SystemSettingsViewSet`, `AccountSettingsViewSet`, `UserSettingsViewSet`
- `ModuleSettingsViewSet`, `AISettingsViewSet`
- `IntegrationSettingsViewSet` - Integration management and testing
- **Billing Module** (`modules/billing/`)
- Credit-based usage system
- Credit transactions tracking (`CreditTransaction` model)
- Usage analytics (`CreditUsageLog` model)
- `CreditService` for credit operations
- Monthly credit replenishment via Celery beat task
- ViewSets: `CreditBalanceViewSet`, `CreditUsageViewSet`, `CreditTransactionViewSet`
- **Billing Module** - All ViewSets refactored to unified format
- `CreditBalanceViewSet` - `balance` action
- `CreditUsageViewSet` - `summary`, `limits` actions
- `CreditTransactionViewSet` - CRUD operations
- **AI Framework** (`ai/`)
- `AIEngine` - Central orchestrator for all AI operations with progress tracking
- `AICore` - Unified API client for OpenAI/Runware with rate calculation
- `BaseAIFunction` - Abstract interface for AI function implementations
- AI function registry system with 5 core functions
- Progress tracking with Celery task state updates
- Cost tracking (token usage and pricing)
- Console step tracker for debugging (`ConsoleStepTracker`)
- Prompt registry system (`PromptRegistry`)
- Model configuration per account via `IntegrationSettings`
- Validators for payload validation
- Celery task wrapper: `run_ai_task`
- **Auth Module** - All ViewSets refactored to unified format
- `AuthViewSet` - `register`, `login`, `change_password`, `refresh_token`, `reset_password`
- `UsersViewSet` - CRUD + `create_user`, `update_role` actions
- `GroupsViewSet`, `AccountsViewSet`, `SubscriptionsViewSet`
- `SiteUserAccessViewSet`, `PlanViewSet`, `IndustryViewSet`, `SeedKeywordViewSet`
- **AI Functions** (`ai/functions/`)
- `auto_cluster.py` - Semantic keyword clustering
- `generate_ideas.py` - Content idea generation from clusters
- `generate_content.py` - Full blog post generation with HTML
- `generate_image_prompts.py` - Extract image prompts from content
- `generate_images.py` - Image generation via DALL-E 3 / Runware
#### Frontend Refactoring
- **fetchAPI Wrapper** (`frontend/src/services/api.ts`)
- Automatically extracts `data` field from unified format responses
- Handles paginated responses (`results` at top level)
- Properly throws errors for `success: false` responses
- Removed redundant `response?.data || response` checks across codebase
- **API Infrastructure** (`api/`)
- Unified response format: `{success, data, message, request_id}`
- Response helpers: `success_response()`, `error_response()`, `paginated_response()`
- Request ID tracking via `RequestIDMiddleware`
- Resource tracking via `ResourceTrackingMiddleware`
- Rate limiting with `DebugScopedRateThrottle` (bypass in DEBUG mode)
- Custom pagination: `CustomPageNumberPagination` (default: 10, max: 100)
- OpenAPI 3.0 schema via drf-spectacular
- Swagger UI at `/api/docs/`
- ReDoc at `/api/redoc/`
- Centralized exception handling with unified error format
- **All Frontend Pages Updated**
- Removed redundant response data extraction
- All pages now correctly consume unified API format
- Error handling standardized across all components
- Pagination handling standardized
- **Celery Integration** (`celery.py`)
- Async task processing for AI operations
- Celery beat for scheduled tasks
- Beat schedule: monthly credit replenishment, automation rule execution (every 5 min)
- Task autodiscovery from all installed apps
- **Component Updates**
- `FormModal` - Now accepts `React.ReactNode` for title prop
- `ComponentCard` - Updated to support status badges in titles
- `ResourceDebugOverlay` - Fixed to extract data from unified format
- `ApiStatusIndicator` - Restricted to aws-admin accounts and API monitor page
#### Frontend Core
- **React 19 Application** (`frontend/`)
- Vite 6.1.0 build system with fast HMR
- TypeScript 5.7.2 for type safety
- React Router v7.9.5 for client-side routing
- Zustand 5.0.8 state management with localStorage persistence
- Lazy loading for all module pages (code splitting)
- Tailwind CSS 4.0.8 for styling
### Fixed
- **Authentication** (`pages/AuthPages/`, `store/authStore.ts`)
- JWT-based authentication with automatic token refresh
- Login/signup pages
- Protected routes with `ProtectedRoute` component
- Auth store with Zustand (user, token, refreshToken state)
- Auto token refresh on 401 errors
#### Bug Fixes
- **Keyword Edit Form** - Now correctly populates existing values when editing
- Added `key` prop to force re-render when form data changes
- Fixed `seed_keyword_id` value handling for select dropdown
- **Module Pages**
- **Planner** (`pages/Planner/`): Keywords list, Clusters view, Ideas dashboard, Keyword opportunities
- **Writer** (`pages/Writer/`): Tasks dashboard, Content viewer with HTML preview, Drafts, Published list, Images gallery
- **Linker** (`pages/Linker/`): Link analysis dashboard, Content list with link suggestions
- **Optimizer** (`pages/Optimizer/`): Optimization dashboard, Content selector, Analysis preview
- **Thinker** (`pages/Thinker/`): AI prompts editor, Author profiles, Strategies, Image testing
- **Billing** (`pages/Billing/`): Credit balance, Transaction history, Usage analytics
- **Automation** (`pages/Automation/`): Rules management, Scheduled tasks list
- **Settings** (`pages/Settings/`): General, Users, Subscriptions, System, AI settings, API monitor
- **Auto-Cluster Function** - Now works correctly with unified API format
- Updated `autoClusterKeywords()` to wrap response with `success` field
- Proper error handling and response extraction
- **UI Components** (`components/`)
- Reusable components library
- ApexCharts for data visualization
- Heroicons for icons
- Responsive layouts with Tailwind
- Form components with validation
- Modal system
- Loading states and skeletons
- **ResourceDebugOverlay** - Fixed data extraction from unified API responses
- Extracts `data` field from `{success: true, data: {...}}` responses
- Added null safety checks for all property accesses
- Validates data structure before adding to metrics
- **API Integration** (`api/`, `services/`)
- Axios client with automatic token injection
- Request/response interceptors
- Automatic token refresh on 401
- Module-specific API clients (planner, writer, linker, etc.)
- `fetchAPI` wrapper with unified format handling
- Error handling with toast notifications
- **API Response Handling** - Fixed all instances of incorrect data extraction
- Removed `response?.data || response` redundant checks
- Removed `response.results || []` redundant checks
- All API functions now correctly handle unified format
- **State Management** (`store/`)
- `authStore` - User authentication state
- `siteStore` - Site and sector context
- Module-specific stores (plannerStore, writerStore, etc.)
- Global app state (loading, errors, notifications)
- Zustand persist middleware for localStorage
- **React Hooks Error** - Fixed "Rendered more hooks than during the previous render"
- Moved all hooks to top of component before conditional returns
- Fixed `ApiStatusIndicator` component hook ordering
#### WordPress Plugin
- **Core Plugin** (`igny8-wp-integration/`)
- Plugin version 1.0.0
- WordPress 5.0+ compatibility
- PHP 7.4+ requirement
- Main file: `igny8-bridge.php`
- Uninstall cleanup: `uninstall.php`
- **TypeScript Errors** - Fixed all type errors related to unified API format
- Added nullish coalescing for `toLocaleString()` calls
- Added null checks before `Object.entries()` calls
- Fixed all undefined property access errors
- **API Client** (`includes/class-igny8-api.php`)
- `Igny8API` class for backend communication
- API key authentication (primary method)
- JWT token authentication support (fallback)
- Automatic retry on 401 errors
- Request/response parsing with unified format support
- Methods: `connect()`, `get()`, `post()`, `put()`, `delete()`, `parse_response()`
#### System Health
- **System Status Page** - Fixed redundant data extraction
- Now correctly uses extracted data from `fetchAPI`
- All system metrics display correctly
- **REST API Endpoints** (`includes/class-igny8-rest-api.php`)
- `GET /wp-json/igny8/v1/site-metadata/` - Export site structure
- `GET /wp-json/igny8/v1/post-by-task-id/{id}` - Lookup by task ID
- `GET /wp-json/igny8/v1/post-by-content-id/{id}` - Lookup by content ID
- `POST /wp-json/igny8/v1/posts/` - Create post from IGNY8
- `PUT /wp-json/igny8/v1/posts/{id}` - Update post from IGNY8
- API key authentication via `X-IGNY8-API-Key` header
### Security
- Rate limiting bypass only for aws-admin accounts and admin/developer roles
- Request ID tracking for all API requests
- Centralized error handling prevents information leakage
- **Synchronization** (`sync/`)
- **WP → IGNY8** (`post-sync.php`): Post status sync on `save_post` hook
- **IGNY8 → WP** (`igny8-to-wp.php`): Content publishing via REST API
- **Taxonomy Sync** (`taxonomy-sync.php`): Taxonomy term synchronization
- **Hooks** (`hooks.php`): WordPress action/filter hook registration
- Bidirectional sync with status mapping
- Post meta tracking: `_igny8_task_id`, `_igny8_content_id`, `_igny8_wordpress_status`, `_igny8_last_synced`, `_igny8_managed`
### Testing
- **Admin Interface** (`admin/`)
- Settings page at Settings → IGNY8 API (`settings.php`)
- API key, email, password configuration
- Connection testing button
- Post columns showing IGNY8 status (`class-admin-columns.php`)
- Post meta boxes in editor (`class-post-meta-boxes.php`)
- Admin class: `Igny8Admin` (`class-admin.php`)
- **Comprehensive Test Suite**
- Created complete unit and integration test suite for Unified API Standard v1.0
- 13 test files with ~115 test methods covering all API components
- Test coverage: 100% of API Standard components
- **Data Collection** (`data/`)
- Full site metadata collection (`site-collection.php`)
- Post type discovery with counts
- Taxonomy discovery with counts
- Link graph extraction (`link-graph.php`)
- Semantic mapping (`semantic-mapping.php`)
- WooCommerce integration support (`woocommerce.php`)
- **Unit Tests** (`backend/igny8_core/api/tests/`)
- `test_response.py` - Tests for response helper functions (18 tests)
- Tests `success_response()`, `error_response()`, `paginated_response()`
- Tests request ID generation and inclusion
- Tests status code mapping and error messages
- `test_exception_handler.py` - Tests for custom exception handler (12 tests)
- Tests all exception types (ValidationError, AuthenticationFailed, PermissionDenied, NotFound, Throttled, etc.)
- Tests debug mode behavior and debug info inclusion
- Tests field-specific and non-field error handling
- `test_permissions.py` - Tests for permission classes (20 tests)
- Tests `IsAuthenticatedAndActive`, `HasTenantAccess`, `IsViewerOrAbove`, `IsEditorOrAbove`, `IsAdminOrOwner`
- Tests role-based access control and tenant isolation
- Tests admin/system account bypass logic
- `test_throttles.py` - Tests for rate limiting (11 tests)
- Tests `DebugScopedRateThrottle` bypass logic (DEBUG mode, env flag, admin/system accounts)
- Tests rate parsing and throttle header generation
- **Integration Tests** (`backend/igny8_core/api/tests/`)
- `test_integration_base.py` - Base test class with common fixtures and helper methods
- `test_integration_planner.py` - Planner module endpoint tests (12 tests)
- Tests CRUD operations for keywords, clusters, ideas
- Tests AI actions (auto_cluster)
- Tests error scenarios and validation
- `test_integration_writer.py` - Writer module endpoint tests (6 tests)
- Tests CRUD operations for tasks, content, images
- Tests error scenarios
- `test_integration_system.py` - System module endpoint tests (5 tests)
- Tests status, prompts, settings, integrations endpoints
- `test_integration_billing.py` - Billing module endpoint tests (5 tests)
- Tests credits, usage, transactions endpoints
- `test_integration_auth.py` - Auth module endpoint tests (8 tests)
- Tests login, register, user management endpoints
- Tests authentication flows and error scenarios
- `test_integration_errors.py` - Error scenario tests (6 tests)
- Tests 400, 401, 403, 404, 429, 500 error responses
- Tests unified error format across all error types
- `test_integration_pagination.py` - Pagination tests (10 tests)
- Tests pagination across all modules
- Tests page size, page parameter, max page size limits
- Tests empty results handling
- `test_integration_rate_limiting.py` - Rate limiting integration tests (7 tests)
- Tests throttle headers presence
- Tests bypass logic for admin/system accounts and DEBUG mode
- Tests different throttle scopes per module
- **Test Verification**
- All tests verify unified response format (`{success, data/results, message, errors, request_id}`)
- All tests verify proper HTTP status codes
- All tests verify error format consistency
- All tests verify pagination format consistency
- All tests verify request ID inclusion
- **Test Documentation**
- Created `backend/igny8_core/api/tests/README.md` with test structure and running instructions
- Created `backend/igny8_core/api/tests/TEST_SUMMARY.md` with comprehensive test statistics
- Created `backend/igny8_core/api/tests/run_tests.py` test runner script
### Documentation
- **OpenAPI/Swagger Integration**
- Installed and configured `drf-spectacular` for OpenAPI 3.0 schema generation
- Created Swagger UI endpoint: `/api/docs/`
- Created ReDoc endpoint: `/api/redoc/`
- Created OpenAPI schema endpoint: `/api/schema/`
- Configured comprehensive API documentation with code samples
- Added custom authentication extensions for JWT Bearer tokens
- **Comprehensive Documentation Files**
- `docs/API-COMPLETE-REFERENCE.md` - Complete unified API reference (consolidated from multiple files)
- Quick start guide
- Endpoint reference
- Code examples (Python, JavaScript, cURL)
- Response format details
- `docs/AUTHENTICATION-GUIDE.md` - Authentication and authorization guide
- JWT Bearer token authentication
- Token management and refresh
- Code examples in Python and JavaScript
- Security best practices
- `docs/ERROR-CODES.md` - Complete error code reference
- HTTP status codes (200, 201, 400, 401, 403, 404, 409, 422, 429, 500)
- Field-specific error messages
- Error handling best practices
- Common error scenarios and solutions
- `docs/RATE-LIMITING.md` - Rate limiting and throttling guide
- Rate limit scopes and limits
- Handling rate limits (429 responses)
- Best practices and code examples
- Request queuing and caching strategies
- `docs/MIGRATION-GUIDE.md` - Migration guide for API consumers
- What changed in v1.0
- Step-by-step migration instructions
- Code examples (before/after)
- Breaking and non-breaking changes
- `docs/WORDPRESS-PLUGIN-INTEGRATION.md` - WordPress plugin integration guide
- Complete PHP API client class
- Authentication implementation
- Error handling
- WordPress admin integration
- Best practices
- `docs/README.md` - Documentation index and quick start
- **OpenAPI Schema Configuration**
- Configured comprehensive API description with features overview
- Added authentication documentation
- Added response format examples
- Added rate limiting documentation
- Added pagination documentation
- Configured endpoint tags (Authentication, Planner, Writer, System, Billing)
- Added code samples in Python and JavaScript
- **Schema Extensions**
- Created `backend/igny8_core/api/schema_extensions.py` for custom authentication
- JWT Bearer token authentication extension
- CSRF-exempt session authentication extension
- Proper OpenAPI security scheme definitions
---
## [1.0.0] - 2025-01-XX
### Added
#### Documentation System
- Complete documentation structure with 7 core documents
- Documentation management system with versioning
- Changelog management system
- DRY principles documentation
- Self-explaining documentation for AI agents
#### Core Features
- Multi-tenancy system with account isolation
- Authentication (login/register) with JWT
- RBAC permissions (Developer, Owner, Admin, Editor, Viewer, System Bot)
- Account > Site > Sector hierarchy
- Multiple sites can be active simultaneously
- Maximum 5 active sectors per site
#### Planner Module
- Keywords CRUD operations
- Keyword import/export (CSV)
- Keyword filtering and organization
- AI-powered keyword clustering
- Clusters CRUD operations
- Content ideas generation from clusters
- Content ideas CRUD operations
- Keyword-to-cluster mapping
- Cluster metrics and analytics
#### Writer Module
- Tasks CRUD operations
- AI-powered content generation
- Content editing and review
- Image prompt extraction
- AI-powered image generation (OpenAI DALL-E, Runware)
- Image management
- WordPress integration (publishing)
#### Thinker Module
- AI prompt management
- Author profile management
- Content strategy management
- Image generation testing
#### System Module
- Integration settings (OpenAI, Runware)
- API key configuration
- Connection testing
- System status and monitoring
#### Billing Module
- Credit balance tracking
- Credit transactions
- Usage logging
- Cost tracking
#### Frontend
- Configuration-driven UI system
- 4 universal templates (Dashboard, Table, Form, System)
- Complete component library
- Zustand state management
- React Router v7 routing
- Progress tracking for AI tasks
- Responsive design
#### Backend
- RESTful API with DRF
- Automatic account isolation
- Site access control
- Celery async task processing
- Progress tracking for Celery tasks
- Unified AI framework
- Database logging
#### AI Functions
- Auto Cluster Keywords
- Generate Ideas
- Generate Content
- Generate Image Prompts
- Generate Images
- Test OpenAI connection
- Test Runware connection
- Test image generation
- **Supporting Classes** (`includes/`)
- `Igny8Site` - Site data collection and export
- `Igny8Webhooks` - Webhook handlers (legacy)
- `Igny8WebhookLogs` - Webhook logging
- `Igny8LinkQueue` - Link processing queue
- Helper functions in `functions.php`
#### Infrastructure
- Docker-based containerization
- Two-stack architecture (infra, app)
- Caddy reverse proxy
- PostgreSQL database
- Redis cache and Celery broker
- pgAdmin database administration
- FileBrowser file management
- **Docker Deployment** (`docker-compose.app.yml`)
- Multi-container setup for development
- Services: PostgreSQL, Redis, Django backend, Celery worker, Celery beat
- Volume persistence for database and media
- Network isolation
- **Database** (PostgreSQL 14+)
- Multi-tenant data model with account isolation
- Optimized indexes for common queries
- JSON fields for flexible configuration storage
- Database migrations system
- **Task Queue** (Celery + Redis)
- Redis as message broker
- Celery worker for async tasks
- Celery beat for scheduled tasks
- Progress tracking with task state updates
### Documentation
- **Master Documentation** (`master-docs/`)
- Complete architecture documentation
- API reference with endpoint details
- Frontend and backend implementation guides
- WordPress plugin integration guide
#### Documentation Files Created
- `docs/00-DOCUMENTATION-MANAGEMENT.md` - Documentation and changelog management system
- `docs/01-TECH-STACK-AND-INFRASTRUCTURE.md` - Technology stack and infrastructure
- `docs/02-APPLICATION-ARCHITECTURE.md` - Application architecture with workflows
- `docs/03-FRONTEND-ARCHITECTURE.md` - Frontend architecture documentation
- `docs/04-BACKEND-IMPLEMENTATION.md` - Backend implementation reference
- `docs/05-AI-FRAMEWORK-IMPLEMENTATION.md` - AI framework implementation reference
- `docs/06-FUNCTIONAL-BUSINESS-LOGIC.md` - Functional business logic documentation
- **Project Documentation**
- `MASTER_REFERENCE.md` - Complete system architecture and navigation
- `README.md` - Quick start and setup guide
- `CHANGELOG.md` - This file
#### Documentation Features
- Complete workflow documentation
- Feature completeness
- No code snippets (workflow-focused)
- Accurate state reflection
- Cross-referenced documents
- Self-explaining structure for AI agents
### Changed
- N/A (Initial release)
### Deprecated
- N/A (Initial release)
### Removed
- N/A (Initial release)
### Fixed
- N/A (Initial release)
### Security
- JWT token authentication with 15-minute expiry and refresh tokens
- Secure API key storage in WordPress using encryption helpers
- CSRF protection on all forms
- SQL injection prevention via Django ORM
- XSS protection via Django template escaping
- HTTPS enforcement in production
- Account isolation at database level with automatic filtering
- Permission-based access control with role matrix
- Rate limiting to prevent abuse
- Request ID tracking for audit trails
---
## Version History
### Current Version: 1.0.0
**Status**: Production
**Date**: 2025-01-XX
### Version Format
- **MAJOR**: Breaking changes, major feature additions, architecture changes
- **MINOR**: New features, new modules, significant enhancements
- **PATCH**: Bug fixes, small improvements, documentation updates
### Version Update Rules
1. **MAJOR**: Only updated when user confirms major release
2. **MINOR**: Updated when user confirms new feature is complete
3. **PATCH**: Updated when user confirms bug fix is complete
**IMPORTANT**: Never update version without user confirmation.
- **1.0.0** (2025-11-24) - Initial release with complete feature set
---
## Planned Features
## Versioning Strategy
### In Progress
- Planner Dashboard enhancement with KPIs
- Automation & CRON tasks
- Advanced analytics
- **Major version** (X.0.0) - Breaking changes, major architectural changes
- **Minor version** (1.X.0) - New features, new modules, backward compatible
- **Patch version** (1.0.X) - Bug fixes, minor improvements, documentation updates
### Future
- Analytics module enhancements
- Advanced scheduling features
---
## Upgrade Notes
### Upgrading to 1.0.0
This is the initial release. No upgrade path required.
Future upgrade notes will be documented here for each version.
---
## Future Roadmap
Planned features and improvements (subject to change):
- Enhanced analytics and reporting
- Additional AI model integrations
- Stripe payment integration
- Plan limits enforcement
- Advanced reporting
- Advanced automation workflows
- Mobile app support
- API documentation (Swagger/OpenAPI)
- Unit and integration tests for unified API
- API webhooks
- Collaborative editing features
- Multi-language support
See project board for current priorities and development status.
---
## Notes
**Note:** This changelog is maintained according to [Keep a Changelog](https://keepachangelog.com/) principles and only updated after user confirmation of completed features and fixes.
- All features are documented in detail in the respective documentation files
- Workflows are complete and accurate
- System is production-ready
- Documentation is maintained and updated regularly
- Changelog is only updated after user confirmation
---
**For AI Agents**: Before making any changes, read `docs/00-DOCUMENTATION-MANAGEMENT.md` for complete guidelines on versioning, changelog management, and DRY principles.

1360
MASTER_REFERENCE.md Normal file
View File

File diff suppressed because it is too large Load Diff

358
README.md Normal file
View File

@@ -0,0 +1,358 @@
# IGNY8 - AI-Powered SEO Content Platform
**Version:** 1.0.0
**License:** Proprietary
**Website:** https://igny8.com
---
## What is IGNY8?
IGNY8 is a full-stack SaaS platform that combines AI-powered content generation with intelligent SEO management. It helps content creators, marketers, and agencies streamline their content workflow from keyword research to published articles.
### Key Features
- 🔍 **Smart Keyword Management** - Import, cluster, and organize keywords with AI
- ✍️ **AI Content Generation** - Generate SEO-optimized blog posts using GPT-4
- 🖼️ **AI Image Creation** - Auto-generate featured and in-article images
- 🔗 **Internal Linking** - AI-powered link suggestions for SEO
- 📊 **Content Optimization** - Analyze and score content quality
- 🔄 **WordPress Integration** - Bidirectional sync with WordPress sites
- 📈 **Usage-Based Billing** - Credit system for AI operations
- 👥 **Multi-Tenancy** - Manage multiple sites and teams
---
## Repository Structure
This monorepo contains two main applications:
```
igny8/
├── backend/ # Django REST API + Celery
├── frontend/ # React + Vite SPA
├── master-docs/ # Architecture documentation
└── docker-compose.app.yml # Docker deployment config
```
**Separate Repository:**
- [igny8-wp-integration](https://github.com/alorig/igny8-wp-integration) - WordPress bridge plugin
---
## Quick Start
### Prerequisites
- **Python 3.11+**
- **Node.js 18+**
- **PostgreSQL 14+**
- **Redis 7+**
- **Docker** (optional, recommended for local development)
### Local Development with Docker
1. **Clone the repository**
```powershell
git clone https://github.com/alorig/igny8-app.git
cd igny8
```
2. **Set environment variables**
Create `.env` file in `backend/` directory:
```env
SECRET_KEY=your-secret-key-here
DEBUG=True
DATABASE_URL=postgresql://postgres:postgres@db:5432/igny8
REDIS_URL=redis://redis:6379/0
OPENAI_API_KEY=your-openai-key
RUNWARE_API_KEY=your-runware-key
```
3. **Start services**
```powershell
docker-compose -f docker-compose.app.yml up --build
```
4. **Access applications**
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/api/docs/
- Django Admin: http://localhost:8000/admin/
### Manual Setup (Without Docker)
#### Backend Setup
```powershell
cd backend
# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# Install dependencies
pip install -r requirements.txt
# Run migrations
python manage.py migrate
# Create superuser
python manage.py createsuperuser
# Run development server
python manage.py runserver
```
In separate terminals, start Celery:
```powershell
# Celery worker
celery -A igny8_core worker -l info
# Celery beat (scheduled tasks)
celery -A igny8_core beat -l info
```
#### Frontend Setup
```powershell
cd frontend
# Install dependencies
npm install
# Start dev server
npm run dev
```
---
## Project Architecture
### System Overview
```
User Interface (React)
↓
REST API (Django)
↓
┌───────┴────────┐
│ │
Database AI Engine
(PostgreSQL) (Celery + OpenAI)
│
WordPress Plugin
(Bidirectional Sync)
```
### Tech Stack
**Backend:**
- Django 5.2+ (Python web framework)
- Django REST Framework (API)
- PostgreSQL (Database)
- Celery (Async task queue)
- Redis (Message broker)
- OpenAI API (Content generation)
**Frontend:**
- React 19 (UI library)
- Vite 6 (Build tool)
- Zustand (State management)
- React Router v7 (Routing)
- Tailwind CSS 4 (Styling)
**WordPress Plugin:**
- PHP 7.4+ (WordPress compatibility)
- REST API integration
- Bidirectional sync
---
## How IGNY8 Works
### Content Creation Workflow
```
1. Import Keywords
↓
2. AI Clusters Keywords
↓
3. Generate Content Ideas
↓
4. Create Writer Tasks
↓
5. AI Generates Content
↓
6. AI Creates Images
↓
7. Publish to WordPress
↓
8. Sync Status Back
```
### WordPress Integration
The WordPress bridge plugin (`igny8-wp-integration`) creates a bidirectional connection:
- **IGNY8 → WordPress:** Publish AI-generated content to WordPress
- **WordPress → IGNY8:** Sync post status updates back to IGNY8
**Setup:**
1. Install WordPress plugin on your site
2. Generate API key in IGNY8 app
3. Connect plugin using email, password, and API key
4. Plugin syncs automatically
---
## Documentation
Comprehensive documentation is available in the `master-docs/` directory:
- **[MASTER_REFERENCE.md](./MASTER_REFERENCE.md)** - Complete system architecture and navigation
- **[API-COMPLETE-REFERENCE.md](./master-docs/API-COMPLETE-REFERENCE.md)** - Full API documentation
- **[02-APPLICATION-ARCHITECTURE.md](./master-docs/02-APPLICATION-ARCHITECTURE.md)** - System design
- **[04-BACKEND-IMPLEMENTATION.md](./master-docs/04-BACKEND-IMPLEMENTATION.md)** - Backend details
- **[03-FRONTEND-ARCHITECTURE.md](./master-docs/03-FRONTEND-ARCHITECTURE.md)** - Frontend details
- **[WORDPRESS-PLUGIN-INTEGRATION.md](./master-docs/WORDPRESS-PLUGIN-INTEGRATION.md)** - Plugin integration guide
---
## Development Workflow
### Running Tests
```powershell
# Backend tests
cd backend
python manage.py test
# Frontend tests
cd frontend
npm run test
```
### Code Quality
```powershell
# Frontend linting
cd frontend
npm run lint
```
### Building for Production
```powershell
# Backend
cd backend
python manage.py collectstatic
# Frontend
cd frontend
npm run build
```
---
## API Overview
**Base URL:** `https://api.igny8.com/api/v1/`
**Authentication:** JWT Bearer token
**Key Endpoints:**
- `/auth/login/` - User authentication
- `/planner/keywords/` - Keyword management
- `/planner/clusters/` - Keyword clusters
- `/writer/tasks/` - Content tasks
- `/writer/content/` - Generated content
- `/integration/integrations/` - WordPress integrations
**Interactive Docs:**
- Swagger UI: https://api.igny8.com/api/docs/
- ReDoc: https://api.igny8.com/api/redoc/
See [API-COMPLETE-REFERENCE.md](./master-docs/API-COMPLETE-REFERENCE.md) for full documentation.
---
## Multi-Tenancy
IGNY8 supports complete account isolation:
```
Account (Organization)
├── Users (with roles: owner, admin, editor, viewer)
├── Sites (multiple WordPress sites)
└── Sectors (content categories)
└── Keywords, Clusters, Content
```
All data is automatically scoped to the authenticated user's account.
---
## Contributing
This is a private repository. For internal development:
1. Create feature branch: `git checkout -b feature/your-feature`
2. Make changes and test thoroughly
3. Commit: `git commit -m "Add your feature"`
4. Push: `git push origin feature/your-feature`
5. Create Pull Request
---
## Deployment
### Production Deployment
1. **Set production environment variables**
2. **Build frontend:** `npm run build`
3. **Collect static files:** `python manage.py collectstatic`
4. **Run migrations:** `python manage.py migrate`
5. **Use docker-compose:** `docker-compose -f docker-compose.app.yml up -d`
### Environment Variables
Required for production:
```env
SECRET_KEY=<random-secret-key>
DEBUG=False
ALLOWED_HOSTS=api.igny8.com,app.igny8.com
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://host:6379/0
OPENAI_API_KEY=<openai-key>
RUNWARE_API_KEY=<runware-key>
USE_SECURE_COOKIES=True
```
---
## Support
For support and questions:
- Check [MASTER_REFERENCE.md](./MASTER_REFERENCE.md) for detailed documentation
- Review API docs at `/api/docs/`
- Contact development team
---
## License
Proprietary. All rights reserved.
---
## Changelog
See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.
---
**Built with ❤️ by the IGNY8 team**

404
master-docs/00-DOCUMENTATION-MANAGEMENT.md
View File

@@ -1,404 +0,0 @@
# IGNY8 Documentation & Changelog Management System
**Last Updated:** 2025-01-XX
**Purpose:** Complete guide for managing documentation versioning, changelog updates, and DRY principles. This document must be read by all AI agents at the start of any session.
---
## Table of Contents
1. [Versioning System](#versioning-system)
2. [Changelog Management](#changelog-management)
3. [Documentation Update Process](#documentation-update-process)
4. [DRY Principles & Standards](#dry-principles--standards)
5. [AI Agent Instructions](#ai-agent-instructions)
---
## Versioning System
### Version Format
**Format:** `MAJOR.MINOR.PATCH` (Semantic Versioning)
- **MAJOR**: Breaking changes, major feature additions, architecture changes
- **MINOR**: New features, new modules, significant enhancements
- **PATCH**: Bug fixes, small improvements, documentation updates
**Current Version:** `1.0.0`
### Version Tracking
**Location:**
- Root `CHANGELOG.md` - Main version history
- Each documentation file header - Last updated date
**Version Update Rules:**
- **MAJOR**: Only updated when user confirms major release
- **MINOR**: Updated when user confirms new feature is complete
- **PATCH**: Updated when user confirms bug fix is complete
### Version Update Process
1. **Code Change Made**: Developer/AI makes code changes
2. **User Confirmation**: User confirms fix/feature is complete
3. **Version Update**: Update version in CHANGELOG.md
4. **Changelog Entry**: Add entry to CHANGELOG.md
5. **Documentation Update**: Update relevant documentation files if needed
**IMPORTANT**: Never update version or changelog without user confirmation that the change is complete and working.
---
## Changelog Management
### Changelog Location
**File:** `/CHANGELOG.md` (root directory)
### Changelog Structure
```markdown
## [Version] - YYYY-MM-DD
### Added
- New features, modules, or capabilities
### Changed
- Changes to existing features or behavior
### Fixed
- Bug fixes and corrections
### Deprecated
- Features that will be removed in future versions
### Removed
- Features that have been removed
### Security
- Security fixes and improvements
```
### Changelog Entry Format
Each entry must include:
- **Date**: YYYY-MM-DD format
- **Type**: Added, Changed, Fixed, Deprecated, Removed, Security
- **Description**: Clear, concise description of the change
- **Affected Areas**: Modules, components, or features affected
- **Documentation**: Reference to updated documentation files (if any)
### Example Changelog Entry
```markdown
## [1.0.1] - 2025-01-15
### Fixed
- Fixed keyword clustering issue where keywords were not properly linked to clusters
- **Affected**: Planner Module, Keyword Clustering
- **Documentation**: Updated 06-FUNCTIONAL-BUSINESS-LOGIC.md (Keyword Clustering section)
### Added
- Added bulk delete functionality for content ideas
- **Affected**: Planner Module, Content Ideas
- **Documentation**: Updated 06-FUNCTIONAL-BUSINESS-LOGIC.md (Content Ideas Management section)
```
### Changelog Update Rules
1. **Only Update After User Confirmation**: Never add changelog entries until user confirms the change is complete
2. **One Entry Per Change**: Each fix or feature gets its own entry
3. **Chronological Order**: Newest entries at the top
4. **Be Specific**: Include what was changed, why, and where
5. **Link Documentation**: Reference updated documentation files
6. **Version Bump**: Update version number when adding entries
### Changelog Categories
**Added**: New features, new modules, new endpoints, new functions
**Changed**: Modified existing features, updated workflows, refactored code
**Fixed**: Bug fixes, error corrections, issue resolutions
**Deprecated**: Features marked for removal (include migration path)
**Removed**: Features that have been completely removed
**Security**: Security patches, vulnerability fixes, access control updates
---
## Documentation Update Process
### When to Update Documentation
1. **New Feature Added**: Update relevant documentation files
2. **Feature Changed**: Update affected sections in documentation
3. **Bug Fixed**: Update documentation if behavior changed
4. **Workflow Modified**: Update workflow documentation
5. **API Changed**: Update API documentation
6. **Architecture Changed**: Update architecture documentation
### Documentation Files Structure
```
master-docs/ # Master documentation (permanent reference)
├── 00-DOCUMENTATION-MANAGEMENT.md # This file (management guide)
├── 01-TECH-STACK-AND-INFRASTRUCTURE.md
├── 02-APPLICATION-ARCHITECTURE.md
├── 03-FRONTEND-ARCHITECTURE.md
├── 04-BACKEND-IMPLEMENTATION.md
├── 05-AI-FRAMEWORK-IMPLEMENTATION.md
├── 06-FUNCTIONAL-BUSINESS-LOGIC.md # Includes complete workflow documentation
├── API-COMPLETE-REFERENCE.md
└── WORDPRESS-PLUGIN-INTEGRATION.md
active-workflow-docs/ # Current state and active work (single file)
└── CURRENT_WORKFLOW_STATUS.md # Single source of truth for current system state
```
**Note:** The `refactor-plan/` folder has been removed after consolidating relevant content into master docs.
### Documentation Update Checklist
- [ ] Identify which documentation file(s) need updating
- [ ] Update the relevant section(s)
- [ ] Update "Last Updated" date in file header
- [ ] Add changelog entry (after user confirmation)
- [ ] Verify all links still work
- [ ] Ensure consistency across all documentation
### Documentation Standards
1. **No Code Snippets**: Documentation focuses on workflows, features, and architecture
2. **Complete Coverage**: All features and workflows must be documented
3. **Accurate State**: Documentation must reflect current system state
4. **Clear Structure**: Use consistent headings and formatting
5. **Cross-References**: Link related sections and documents
---
## DRY Principles & Standards
### DRY (Don't Repeat Yourself) Philosophy
**Core Principle**: Use existing, predefined, standardized components, utilities, functions, and configurations instead of creating parallel systems or duplicating code.
### Frontend DRY Standards
#### Components
**MUST USE Existing Components:**
- **Templates**: Use 4 universal templates (DashboardTemplate, TablePageTemplate, FormPageTemplate, SystemPageTemplate)
- **UI Components**: Use components from `/frontend/src/components/`
- **Common Components**: Use ScrollToTop, GlobalErrorDisplay, LoadingStateMonitor
- **Form Components**: Use existing form components with props and configs
**DO NOT:**
- Create new templates when existing ones can be used
- Duplicate component logic
- Create parallel component systems
- Hardcode UI elements that can use config-driven approach
#### Configuration-Driven Development
**MUST USE Configuration Files:**
- **Page Configs**: `/frontend/src/config/pages/` - Define page structure
- **Snippet Configs**: `/frontend/src/config/snippets/` - Define reusable snippets
- **Route Configs**: `/frontend/src/config/routes.config.ts` - Define routes
- **API Configs**: Use existing API client patterns
**DO NOT:**
- Hardcode page structures
- Create pages without config files
- Duplicate configuration patterns
#### State Management
**MUST USE Existing Stores:**
- **Zustand Stores**: Use stores from `/frontend/src/stores/`
- Auth Store, Site Store, Sector Store
- Planner Store, Writer Store, Billing Store
- Settings Store, Page Size Store, Column Visibility Store
- **React Contexts**: Use contexts from `/frontend/src/contexts/`
- Theme Context, Sidebar Context, Header Metrics Context, Toast Context
**DO NOT:**
- Create new stores for existing functionality
- Duplicate state management logic
- Create parallel state systems
#### Utilities & Helpers
**MUST USE Existing Utilities:**
- **API Client**: Use `/frontend/src/services/api.ts` patterns
- **Hooks**: Use custom hooks from `/frontend/src/hooks/`
- **Utils**: Use utility functions from `/frontend/src/utils/`
- **Constants**: Use constants from `/frontend/src/constants/`
**DO NOT:**
- Create duplicate utility functions
- Implement API calls without using existing patterns
- Create new helper functions when existing ones work
#### CSS & Styling
**MUST USE:**
- **Tailwind CSS**: Use Tailwind utility classes
- **Existing Styles**: Use predefined styles and classes
- **Component Styles**: Use component-level styles from existing components
- **Theme System**: Use theme context for dark/light mode
**DO NOT:**
- Create custom CSS when Tailwind classes exist
- Duplicate styling patterns
- Create parallel style systems
- Hardcode colors or spacing values
### Backend DRY Standards
#### Base Classes
**MUST USE Existing Base Classes:**
- **AccountModelViewSet**: For account-isolated models
- **SiteSectorModelViewSet**: For site/sector-scoped models
- **AccountBaseModel**: For account-isolated models
- **SiteSectorBaseModel**: For site/sector-scoped models
**DO NOT:**
- Create new base classes when existing ones work
- Duplicate filtering logic
- Create parallel isolation systems
#### AI Framework
**MUST USE AI Framework:**
- **BaseAIFunction**: Inherit from this for all AI functions
- **AIEngine**: Use for executing AI functions
- **AICore**: Use for AI API calls
- **PromptRegistry**: Use for prompt management
- **run_ai_task**: Use this Celery task entry point
**DO NOT:**
- Create new AI function patterns
- Duplicate AI execution logic
- Create parallel AI systems
#### Utilities & Services
**MUST USE Existing Services:**
- **CreditService**: For credit management
- **Content Normalizer**: For content processing
- **AI Functions**: Use existing 5 AI functions
- **Middleware**: Use AccountContextMiddleware, ResourceTrackerMiddleware
**DO NOT:**
- Create duplicate service logic
- Implement credit management without CreditService
- Create parallel utility systems
### DRY Violation Detection
**Red Flags:**
- Creating new components when similar ones exist
- Duplicating API call patterns
- Creating new state management when stores exist
- Hardcoding values that should be config-driven
- Creating parallel systems for existing functionality
**Action Required:**
- Check existing components, utilities, and patterns first
- Refactor to use existing systems
- Update documentation if new patterns are truly needed
---
## AI Agent Instructions
### Mandatory Reading
**At the start of EVERY session, AI agents MUST:**
1. Read this file (`00-DOCUMENTATION-MANAGEMENT.md`)
2. Read root `README.md`
3. Read `CHANGELOG.md`
4. Understand versioning system
5. Understand changelog management
6. Understand DRY principles
### Versioning & Changelog Rules for AI Agents
1. **NEVER update version or changelog without user confirmation**
2. **ALWAYS ask user before adding changelog entries**
3. **ONLY update changelog after user confirms change is complete**
4. **ALWAYS follow changelog structure and format**
5. **ALWAYS reference updated documentation files in changelog**
### DRY Principles for AI Agents
1. **ALWAYS check for existing components/utilities before creating new ones**
2. **ALWAYS use configuration-driven approach when possible**
3. **ALWAYS use existing templates and base classes**
4. **NEVER create parallel systems**
5. **NEVER duplicate code that can be reused**
### Documentation Update Rules for AI Agents
1. **ALWAYS update documentation when making changes**
2. **ALWAYS update "Last Updated" date in file header**
3. **ALWAYS maintain consistency across documentation**
4. **ALWAYS verify links after updates**
5. **ALWAYS follow documentation standards**
### Workflow for AI Agents
**When Making Code Changes:**
1. Check existing components/utilities first (DRY)
2. Make code changes
3. Update relevant documentation
4. Wait for user confirmation
5. Add changelog entry (after confirmation)
6. Update version (if needed, after confirmation)
**When User Confirms Fix/Feature:**
1. Add changelog entry following structure
2. Update version if needed
3. Update documentation "Last Updated" dates
4. Verify all changes are documented
### Self-Explaining System
This documentation management system is designed to be self-explaining:
- **Clear Rules**: All rules are explicitly stated
- **Examples**: Examples provided for clarity
- **Structure**: Consistent structure across all documents
- **Cross-References**: Links between related documents
- **Standards**: Clear standards for all operations
**Any AI agent reading this file should understand:**
- How to manage versions
- How to update changelog
- How to follow DRY principles
- How to update documentation
- When to ask for user confirmation
---
## Summary
### Key Principles
1. **Versioning**: Semantic versioning, only update after user confirmation
2. **Changelog**: Structured entries, only after user confirmation
3. **Documentation**: Always update when making changes
4. **DRY**: Always use existing components, utilities, and patterns
5. **Confirmation**: Never update version/changelog without user confirmation
### Lock Status
**Documentation Management System**: ✅ **LOCKED**
This system is finalized and should not be changed without explicit user approval. All AI agents must follow these rules.
---
**Last Updated:** 2025-01-XX (Documentation structure updated)
**Version:** 1.0.0
**Status:** Locked

1180
master-docs/01-TECH-STACK-AND-INFRASTRUCTURE.md
View File

File diff suppressed because it is too large Load Diff

935
master-docs/02-APPLICATION-ARCHITECTURE.md
View File

@@ -1,935 +0,0 @@
# IGNY8 Application Architecture
**Last Updated:** 2025-01-XX (Added 6 missing modules: Linker, Optimizer, Publisher, Site Builder, Automation, Integration)
**Purpose:** Complete application architecture documentation covering system hierarchy, user roles, access control, modules, workflows, data models, multi-tenancy, API architecture, and security.
---
## Table of Contents
1. [System Overview](#system-overview)
2. [System Hierarchy](#system-hierarchy)
3. [User Roles & Access Control](#user-roles--access-control)
4. [Module Organization](#module-organization)
5. [Complete Workflows](#complete-workflows)
6. [Data Models & Relationships](#data-models--relationships)
7. [Multi-Tenancy Architecture](#multi-tenancy-architecture)
8. [API Architecture](#api-architecture)
9. [Security Architecture](#security-architecture)
10. [Integration Points](#integration-points)
---
## System Overview
**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system provides a scalable, multi-account platform that enables users to manage keywords, generate content ideas, create AI-powered content, and publish to WordPress.
### Platform Capabilities
| Capability | Description | Module |
|------------|-------------|--------|
| **Keyword Management** | Import, organize, filter, and manage SEO keywords | Planner |
| **Keyword Clustering** | AI-powered semantic clustering of related keywords | Planner |
| **Content Ideas** | Generate content ideas from keyword clusters | Planner |
| **Content Generation** | AI-powered blog post and article generation | Writer |
| **Image Generation** | AI-powered image generation (DALL-E, Runware) | Writer |
| **WordPress Integration** | Direct publishing to WordPress sites | Writer |
| **Internal Linking** | AI-powered internal linking suggestions | Linker |
| **Content Optimization** | Content scoring and optimization suggestions | Optimizer |
| **Site Publishing** | Publishing records and site deployment | Publisher |
| **Site Blueprints** | Site structure and page blueprint management | Site Builder |
| **Automation** | Automation rules and scheduled tasks | Automation |
| **Site Integration** | External platform integrations and sync | Integration |
| **Account Management** | Multi-account SaaS with user roles | Auth |
| **Billing & Credits** | Credit-based billing system | Billing |
| **AI Configuration** | Customizable AI prompts and settings | System |
---
## System Hierarchy
### Entity Relationships
```
Account (1) ──< (N) User
Account (1) ──< (1) Subscription ──> (1) Plan
Account (1) ──< (N) Site
Site (1) ──< (1-5) Sector
Sector (1) ──< (N) Keywords, Clusters, ContentIdeas, Tasks
Cluster (1) ──< (N) Keywords (Many-to-Many)
Cluster (1) ──< (N) ContentIdeas
ContentIdeas (1) ──< (N) Tasks
Task (1) ──> (1) Content
Task (1) ──< (N) Images
```
### Hierarchy Details
**Account Level**:
- Top-level organization/workspace
- Contains users, sites, subscriptions, and all data
- Has credit balance and plan assignment
- Status: active, suspended, trial, cancelled
**User Level**:
- Individual user accounts within an account
- Has role (developer, owner, admin, editor, viewer)
- Can belong to only one account
- Access controlled by role and site permissions
**Site Level**:
- Workspace within an account (1-N relationship)
- Can have multiple active sites simultaneously
- Has WordPress integration settings (URL, username, password)
- Can be associated with an industry
- Status: active, inactive, suspended
**Sector Level**:
- Content category within a site (1-5 per site)
- Organizes keywords, clusters, ideas, and tasks
- Can reference an industry sector template
- Status: active, inactive
**Content Level**:
- Keywords, Clusters, ContentIdeas belong to Sector
- Tasks, Content, Images belong to Sector
- All content is automatically associated with Account and Site
---
## User Roles & Access Control
### User Roles
| Role | Access Level | Description | Permissions |
|------|--------------|-------------|-------------|
| **Developer** | System-wide | Full system access, bypasses all restrictions | All accounts, all sites, all data, system settings |
| **Owner** | Account-wide | Full account access, can manage users and billing | All sites in account, user management, billing |
| **Admin** | Account-wide | Account admin access, can manage content and users | All sites in account, content management, user management |
| **Editor** | Site-specific | Content editing access, can manage clusters/tasks | Granted sites only, content editing |
| **Viewer** | Site-specific | Read-only access | Granted sites only, read-only |
| **System Bot** | System-wide | System automation user | All accounts, all sites, all data |
### Access Control Matrix
| User Role | Account Access | Site Access | Data Access | User Management | Billing |
|-----------|----------------|-------------|-------------|------------------|---------|
| Developer | All accounts | All sites | All data | Yes | Yes |
| System Bot | All accounts | All sites | All data | No | No |
| Owner | Own account | All sites in account | All data in account | Yes | Yes |
| Admin | Own account | All sites in account | All data in account | Yes | No |
| Editor | Own account | Granted sites only | Data in granted sites | No | No |
| Viewer | Own account | Granted sites only | Read-only in granted sites | No | No |
### Site Access Control
**Automatic Access**:
- Owners and Admins: Automatic access to all sites in their account
- Developers and System Bot: Access to all sites across all accounts
**Explicit Access**:
- Editors and Viewers: Require explicit `SiteUserAccess` records
- Access granted by Owner or Admin
- Access can be revoked at any time
### Account Isolation
**Principle**: All data is automatically filtered by account.
**Implementation**:
- All models inherit `AccountBaseModel` with `account` ForeignKey
- All ViewSets inherit `AccountModelViewSet` with automatic filtering
- Middleware sets `request.account` from JWT token
- Queries automatically filter by account (except for Developer/System Bot)
---
## Module Organization
### Module Structure
| Module | Purpose | Models | ViewSets | Celery Tasks |
|--------|---------|--------|----------|--------------|
| **Planner** | Keyword management & content planning | Keywords, Clusters, ContentIdeas | KeywordViewSet, ClusterViewSet, ContentIdeasViewSet | auto_cluster_keywords_task, auto_generate_ideas_task |
| **Writer** | Content generation & management | Tasks, Content, Images | TasksViewSet, ContentViewSet, ImagesViewSet | auto_generate_content_task, auto_generate_images_task |
| **Linker** | Internal linking operations | - | LinkerViewSet | - |
| **Optimizer** | Content optimization & scoring | - | OptimizerViewSet | - |
| **Publisher** | Publishing records & site deployment | PublishingRecord, DeploymentRecord | PublishingRecordViewSet, DeploymentRecordViewSet, PublisherViewSet | - |
| **Site Builder** | Site blueprint management | SiteBlueprint, PageBlueprint, SiteBlueprintCluster, SiteBlueprintTaxonomy | SiteBlueprintViewSet, PageBlueprintViewSet, SiteAssetView, SiteBuilderMetadataView | - |
| **Automation** | Automation rules & scheduled tasks | AutomationRule, ScheduledTask | AutomationRuleViewSet, ScheduledTaskViewSet | - |
| **Integration** | External platform integrations | SiteIntegration | IntegrationViewSet | - |
| **System** | Settings, prompts, integrations | AIPrompt, IntegrationSettings, AuthorProfile, Strategy | AIPromptViewSet, IntegrationSettingsViewSet, AuthorProfileViewSet | - |
| **Billing** | Credits, transactions, usage | CreditTransaction, CreditUsageLog | CreditTransactionViewSet, CreditUsageLogViewSet | - |
| **Auth** | Multi-tenancy, users, accounts | Account, User, Plan, Site, Sector | AccountViewSet, UserViewSet, SiteViewSet, SectorViewSet | - |
### Module Dependencies
```
Auth (Core)
├── Planner (depends on Auth)
├── Writer (depends on Auth, Planner)
├── Linker (depends on Auth, Writer)
├── Optimizer (depends on Auth, Writer)
├── Publisher (depends on Auth, Writer, Site Builder)
├── Site Builder (depends on Auth, Planner)
├── Automation (depends on Auth, Planner, Writer)
├── Integration (depends on Auth, Writer)
├── System (depends on Auth)
└── Billing (depends on Auth)
```
### Module Features
#### Planner Module
**Purpose**: Keyword research, clustering, and content idea generation
**Features**:
- Keyword import (CSV/manual)
- Keyword filtering and organization
- AI-powered keyword clustering
- Content idea generation from clusters
- Keyword-to-cluster mapping
- Cluster metrics and analytics
**Models**:
- `Keywords`: Individual keywords with metrics (volume, difficulty, intent)
- `Clusters`: Groups of related keywords
- `ContentIdeas`: Content ideas generated from clusters
#### Writer Module
**Purpose**: Content generation, image generation, and publishing
**Features**:
- Task creation from content ideas
- AI-powered content generation
- Content editing and review
- Image prompt extraction
- AI-powered image generation
- WordPress publishing
**Models**:
- `Tasks`: Content generation tasks
- `Content`: Generated HTML content
- `Images`: Generated images (featured, in-article)
#### System Module
**Purpose**: System configuration and AI settings
**Features**:
- AI prompt management
- Integration settings (OpenAI, Runware)
- Author profile management
- Content strategy management
- System status and monitoring
**Models**:
- `AIPrompt`: AI prompt templates
- `IntegrationSettings`: API keys and configuration
- `AuthorProfile`: Writing style profiles
- `Strategy`: Content strategies
#### Linker Module
**Purpose**: Internal linking operations for content
**Features**:
- AI-powered internal linking suggestions
- Content-to-content link analysis
- Cluster-based link recommendations
- Batch linking operations
- Link validation and management
**ViewSets**:
- `LinkerViewSet`: Process content for internal linking
#### Optimizer Module
**Purpose**: Content optimization and scoring
**Features**:
- Content analysis and scoring
- SEO optimization suggestions
- Readability improvements
- Content quality metrics
- Batch optimization operations
**ViewSets**:
- `OptimizerViewSet`: Optimize and analyze content
#### Publisher Module
**Purpose**: Publishing records and site deployment
**Features**:
- Publishing record tracking
- Deployment record management
- Site definition management
- Publishing status tracking
- Multi-destination publishing support
**Models**:
- `PublishingRecord`: Records of content publishing
- `DeploymentRecord`: Site deployment records
**ViewSets**:
- `PublishingRecordViewSet`: Manage publishing records
- `DeploymentRecordViewSet`: Manage deployment records
- `PublisherViewSet`: Publishing operations
#### Site Builder Module
**Purpose**: Site blueprint and structure management
**Features**:
- Site blueprint creation and management
- Page blueprint management
- Cluster attachment to blueprints
- Taxonomy management
- Site structure generation
- Page content generation
- Site asset management
**Models**:
- `SiteBlueprint`: Site structure blueprints
- `PageBlueprint`: Individual page blueprints
- `SiteBlueprintCluster`: Cluster-to-blueprint links
- `SiteBlueprintTaxonomy`: Taxonomy definitions
**ViewSets**:
- `SiteBlueprintViewSet`: Manage site blueprints
- `PageBlueprintViewSet`: Manage page blueprints
- `SiteAssetView`: File management for site assets
- `SiteBuilderMetadataView`: Metadata for site builder
**Note**: Site Builder Wizard UI has been removed. Blueprints can be managed via API.
#### Automation Module
**Purpose**: Automation rules and scheduled tasks
**Features**:
- Automation rule creation and management
- Scheduled task management
- Rule execution tracking
- Trigger-based automation
- Conditional automation workflows
**Models**:
- `AutomationRule`: Automation rule definitions
- `ScheduledTask`: Scheduled task records
**ViewSets**:
- `AutomationRuleViewSet`: Manage automation rules
- `ScheduledTaskViewSet`: Manage scheduled tasks
#### Integration Module
**Purpose**: External platform integrations and synchronization
**Features**:
- Site integration management (WordPress, etc.)
- Integration connection testing
- Content synchronization
- Sync health monitoring
- Multi-platform publishing support
**Models**:
- `SiteIntegration`: Site-to-platform integration records
**ViewSets**:
- `IntegrationViewSet`: Manage site integrations
#### Billing Module
**Purpose**: Credit management and usage tracking
**Features**:
- Credit balance tracking
- Credit transactions
- Usage logging
- Cost tracking
**Models**:
- `CreditTransaction`: Credit additions and deductions
- `CreditUsageLog`: Usage tracking with cost
#### Auth Module
**Purpose**: Multi-tenancy and user management
**Features**:
- Account management
- User management
- Plan management
- Site and sector management
- Industry templates
**Models**:
- `Account`: Top-level organization
- `User`: User accounts
- `Plan`: Subscription plans
- `Site`: Sites within accounts
- `Sector`: Sectors within sites
- `Industry`: Global industry templates
- `IndustrySector`: Industry sector templates
---
## Complete Workflows
### 1. Account Setup Workflow
**Purpose**: Onboard a new account and user
**Steps**:
1. User signs up via `/signup`
2. Account created with default plan
3. Owner user created and linked to account
4. User signs in via `/signin`
5. JWT token generated and returned
6. Frontend stores token and redirects to dashboard
7. User creates first site (optional)
8. User creates sectors (1-5 per site, optional)
9. User configures integration settings (OpenAI, Runware)
10. System ready for use
**Data Created**:
- 1 Account record
- 1 User record (owner role)
- 1 Subscription record (default plan)
- 0-N Site records
- 0-N Sector records (per site)
- 1 IntegrationSettings record (per integration type)
### 2. Keyword Management Workflow
**Purpose**: Import, organize, and cluster keywords
**Steps**:
1. User navigates to `/planner/keywords`
2. User imports keywords via CSV or manual entry
3. Keywords validated and stored in database
4. Keywords displayed in table with filters
5. User filters keywords by sector, status, intent, etc.
6. User selects keywords for clustering
7. User clicks "Auto Cluster" action
8. Backend validates keyword IDs
9. Celery task queued (`auto_cluster_keywords_task`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
- Loads keywords from database
- Builds AI prompt with keyword data
- Calls OpenAI API for clustering
- Parses cluster response
- Creates Cluster records
- Links keywords to clusters
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays new clusters
16. User can view clusters, edit cluster names, add/remove keywords
**Data Created**:
- N Keyword records (if imported)
- M Cluster records (created by AI)
- N-M Keyword-to-Cluster relationships
**AI Function**: Auto Cluster Keywords
### 3. Content Idea Generation Workflow
**Purpose**: Generate content ideas from keyword clusters
**Steps**:
1. User navigates to `/planner/clusters`
2. User selects one or more clusters
3. User clicks "Generate Ideas" action
4. Backend validates cluster IDs
5. Celery task queued (`auto_generate_ideas_task`)
6. Task ID returned to frontend
7. Frontend polls progress endpoint
8. Celery worker processes task:
- Loads clusters and keywords
- Builds AI prompt with cluster data
- Calls OpenAI API for idea generation
- Parses idea response
- Creates ContentIdeas records
- Links ideas to clusters
9. Progress updates sent to frontend
10. Task completes
11. Frontend displays new content ideas
12. User can view ideas, edit titles, prioritize ideas
**Data Created**:
- N ContentIdeas records (created by AI)
- N ContentIdeas-to-Cluster relationships
**AI Function**: Generate Ideas
### 4. Content Generation Workflow
**Purpose**: Generate AI-powered content from content ideas
**Steps**:
1. User navigates to `/planner/ideas`
2. User selects one or more content ideas
3. User clicks "Create Tasks" action
4. Task records created for each idea
5. User navigates to `/writer/tasks`
6. User selects tasks for content generation
7. User clicks "Generate Content" action
8. Backend validates task IDs
9. Celery task queued (`auto_generate_content_task`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
- Loads tasks and related data (cluster, keywords, idea)
- Builds AI prompt with task data
- Calls OpenAI API for content generation
- Parses HTML content response
- Creates/updates Content records
- Updates task status
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays generated content
16. User can review and edit content
17. User navigates to `/writer/content` to view content
**Data Created**:
- N Task records (from ideas)
- N Content records (generated HTML)
**AI Function**: Generate Content
### 5. Image Generation Workflow
**Purpose**: Generate images for content
**Steps**:
1. User navigates to `/writer/content`
2. User selects content items
3. User clicks "Generate Image Prompts" action (optional, can skip)
4. Backend validates content IDs
5. Celery task queued (`auto_generate_image_prompts_task`)
6. Task processes:
- Loads content HTML
- Builds AI prompt for prompt extraction
- Calls OpenAI API
- Parses image prompts (featured, in-article)
- Creates/updates Images records with prompts
7. User clicks "Generate Images" action
8. Backend validates image IDs
9. Celery task queued (`auto_generate_images_task`)
10. Task processes:
- Loads images with prompts
- Builds image generation prompt
- Calls OpenAI DALL-E or Runware API
- Receives image URLs
- Updates Images records with URLs
11. Images displayed in frontend
12. User can view images, regenerate, or delete
**Data Created**:
- N Images records (with prompts)
- N Images records (with image URLs)
**AI Functions**: Generate Image Prompts, Generate Images
### 6. WordPress Publishing Workflow
**Purpose**: Publish content to WordPress
**Steps**:
1. User navigates to `/writer/content`
2. User selects content to publish
3. User clicks "Publish to WordPress" action
4. Backend validates:
- Site has WordPress URL configured
- Site has WordPress credentials
- Content is ready (status: review or draft)
5. Backend calls WordPress REST API:
- Creates post with content HTML
- Uploads featured image (if available)
- Uploads in-article images (if available)
- Sets post status (draft, publish)
6. WordPress post ID stored in Content record
7. Content status updated to "published"
8. Frontend displays success message
9. User can view published content in WordPress
**Data Updated**:
- Content record: `wp_post_id`, `status` = "published"
**Integration**: WordPress REST API
### 7. User Management Workflow
**Purpose**: Add users to account and manage permissions
**Steps**:
1. Owner/Admin navigates to `/settings/users`
2. User clicks "Add User" action
3. User enters email and selects role
4. Backend creates User record:
- Email validated (unique per account)
- Role assigned
- Account linked
- Password set (or invitation sent)
5. If role is Editor/Viewer:
- Owner/Admin grants site access
- SiteUserAccess records created
6. New user receives invitation email
7. New user signs in and accesses granted sites
**Data Created**:
- 1 User record
- 0-N SiteUserAccess records (for Editor/Viewer roles)
### 8. Integration Configuration Workflow
**Purpose**: Configure AI service integrations
**Steps**:
1. User navigates to `/settings/integration`
2. User selects integration type (OpenAI, Runware)
3. User enters API key
4. User clicks "Test Connection" (optional)
5. Backend validates API key:
- Makes test API call
- Returns connection status
6. User saves integration settings
7. Backend stores API key in IntegrationSettings
8. Integration ready for use in AI functions
**Data Created/Updated**:
- 1 IntegrationSettings record (per integration type)
**Test Functions**: Test OpenAI, Test Runware
---
## Data Models & Relationships
### Core Models
**Account Model**:
- Fields: name, slug, owner, plan, credits, status
- Relationships: Users (1-N), Sites (1-N), Subscription (1-1)
**User Model**:
- Fields: email, account, role
- Relationships: Account (N-1), SiteUserAccess (N-M via SiteUserAccess)
**Plan Model**:
- Fields: name, price, limits (users, sites, keywords, clusters, etc.), credits
- Relationships: Accounts (1-N via Subscription)
**Site Model**:
- Fields: name, slug, domain, industry, status, wp_url, wp_username, wp_app_password
- Relationships: Account (N-1), Sectors (1-N), Industry (N-1)
**Sector Model**:
- Fields: name, slug, site, industry_sector, status
- Relationships: Site (N-1), IndustrySector (N-1), Keywords/Clusters/Ideas/Tasks (1-N)
### Planner Models
**Keywords Model**:
- Fields: keyword, volume, difficulty, intent, cluster (M-N)
- Relationships: Sector (N-1), Clusters (M-N)
**Clusters Model**:
- Fields: name, description, keywords_count, volume
- Relationships: Sector (N-1), Keywords (M-N), ContentIdeas (1-N)
**ContentIdeas Model**:
- Fields: idea_title, description, cluster, status
- Relationships: Sector (N-1), Cluster (N-1), Tasks (1-N)
### Writer Models
**Tasks Model**:
- Fields: title, description, cluster, idea, status, content
- Relationships: Sector (N-1), Cluster (N-1), ContentIdeas (N-1), Content (1-1), Images (1-N)
**Content Model**:
- Fields: task, html_content, word_count, status, wp_post_id
- Relationships: Task (1-1), Images (1-N)
**Images Model**:
- Fields: task, content, image_type, prompt, image_url, status
- Relationships: Task (N-1), Content (N-1)
### System Models
**AIPrompt Model**:
- Fields: prompt_type, prompt_value, account
- Relationships: Account (N-1)
**IntegrationSettings Model**:
- Fields: integration_type, config (JSON), account
- Relationships: Account (N-1)
**AuthorProfile Model**:
- Fields: name, description, tone, language, account
- Relationships: Account (N-1)
**Strategy Model**:
- Fields: name, description, sector, prompt_types, account
- Relationships: Account (N-1), Sector (N-1)
### Billing Models
**CreditTransaction Model**:
- Fields: account, transaction_type, amount, balance_after
- Relationships: Account (N-1)
**CreditUsageLog Model**:
- Fields: account, operation_type, credits_used, cost_usd
- Relationships: Account (N-1)
---
## Multi-Tenancy Architecture
### Account Isolation
**Implementation Levels**:
1. **Model Level**: All models inherit `AccountBaseModel` with `account` ForeignKey
2. **ViewSet Level**: All ViewSets inherit `AccountModelViewSet` with automatic filtering
3. **Middleware Level**: `AccountContextMiddleware` sets `request.account` from JWT
**Filtering**:
- All queries automatically filter by `account = request.account`
- Developer and System Bot users bypass account filtering
- System accounts bypass account filtering
### Site/Sector Hierarchy
**Purpose**: Organize content within accounts
**Structure**:
```
Account
└── Site 1 (Active)
├── Sector 1 (Active)
│ ├── Keywords
│ ├── Clusters
│ ├── ContentIdeas
│ └── Tasks
├── Sector 2 (Active)
└── Sector 3 (Inactive)
└── Site 2 (Active)
└── Sector 1 (Active)
```
**Constraints**:
- Maximum 5 active sectors per site
- Multiple sites can be active simultaneously
- All content must belong to a site and sector
### Data Isolation Flow
```
Request with JWT Token
↓
AccountContextMiddleware
├── Extract Account ID from JWT
├── Load Account Object
└── Set request.account
↓
ViewSet.get_queryset()
├── Check User Role
├── Filter by Account (if not admin/developer)
└── Filter by Accessible Sites (if not owner/admin)
↓
Database Query
↓
Results (Account-Isolated)
```
---
## API Architecture
### API Structure
**Base URL**: `/api/v1/`
**Module Endpoints**:
- `/api/v1/auth/` - Accounts, users, sites, sectors, plans
- `/api/v1/planner/` - Keywords, clusters, ideas
- `/api/v1/writer/` - Tasks, content, images
- `/api/v1/linker/` - Internal linking operations
- `/api/v1/optimizer/` - Content optimization operations
- `/api/v1/publisher/` - Publishing records, deployment records
- `/api/v1/site-builder/` - Site blueprints, page blueprints, assets
- `/api/v1/automation/` - Automation rules, scheduled tasks
- `/api/v1/integration/` - Site integrations, sync operations
- `/api/v1/system/` - Prompts, integrations, author-profiles, strategies
- `/api/v1/billing/` - Credits, transactions, usage
### Authentication Flow
```
1. User Signs In
↓
2. Backend Validates Credentials
↓
3. JWT Token Generated
↓
4. Token Returned to Frontend
↓
5. Frontend Stores Token (localStorage)
↓
6. Frontend Includes Token in Requests (Authorization: Bearer {token})
↓
7. Backend Validates Token
↓
8. Account Context Set
↓
9. Request Processed
```
### Response Format
**Success Response**:
- `success`: true
- `data`: Response data
- `message`: Optional message
**Error Response**:
- `success`: false
- `message`: Error message
- `errors`: Validation errors (if applicable)
**Pagination Response**:
- `count`: Total count
- `next`: Next page URL
- `previous`: Previous page URL
- `results`: Array of results
---
## Security Architecture
### Authentication
**Methods**:
- JWT (JSON Web Tokens) - Primary method
- Session-based auth - Fallback for admin
**Token Management**:
- Tokens stored in localStorage
- Tokens included in `Authorization: Bearer {token}` header
- Token refresh mechanism (future implementation)
### Authorization
**Role-Based Access Control (RBAC)**:
- Role checked on every request
- Permissions enforced at ViewSet level
- Action-level permissions for sensitive operations
**Data Access Control**:
- Account-level: Automatic filtering by account
- Site-level: Filtering by accessible sites
- Action-level: Permission checks in ViewSet actions
### Data Security
**Account Isolation**:
- All queries filtered by account
- Admin/Developer override for system accounts
- No cross-account data leakage
**Site Access Control**:
- Users can only access granted sites
- Admin/Developer override for all sites
- Explicit access grants for Editor/Viewer roles
**API Security**:
- CORS configured for frontend domain
- CSRF enabled for session-based auth
- Input validation via DRF serializers
- Rate limiting (future implementation)
---
## Integration Points
### OpenAI Integration
**Purpose**: Text generation and image generation
**Configuration**:
- API key stored per account in `IntegrationSettings`
- Model selection per account
- Cost tracking per request
**Services Used**:
- GPT models for text generation
- DALL-E for image generation
### Runware Integration
**Purpose**: Alternative image generation service
**Configuration**:
- API key stored per account
- Model selection (e.g., `runware:97@1`)
- Image type selection (realistic, artistic, cartoon)
### WordPress Integration
**Purpose**: Content publishing
**Configuration**:
- WordPress URL per site
- Username and password stored per site
- REST API integration for publishing
**Workflow**:
1. Content generated in IGNY8
2. Images attached
3. Content published to WordPress via REST API
4. Status updated in IGNY8
### Stripe Integration (Planned)
**Purpose**: Payment processing
**Status**: Planned for future implementation
**Features**:
- Subscription management
- Payment processing
- Webhook integration
---
## Summary
The IGNY8 application architecture provides:
1. **Multi-Tenancy**: Complete account isolation with automatic filtering
2. **Hierarchical Organization**: Account > Site > Sector > Content structure
3. **Role-Based Access**: Granular permissions for different user roles
4. **Module-Based Design**: Clear separation of concerns across 10 backend modules
5. **Complete Workflows**: End-to-end workflows from keyword import to publishing
6. **AI Integration**: Unified AI framework for all AI operations
7. **Content Optimization**: Internal linking and content optimization tools
8. **Publishing System**: Multi-destination publishing with deployment tracking
9. **Site Builder**: Site blueprint and structure management (API-based)
10. **Automation**: Rule-based automation and scheduled tasks
11. **Integration**: External platform integrations and synchronization
12. **WordPress Integration**: Direct publishing to WordPress sites
13. **Credit System**: Credit-based billing and usage tracking
14. **Security First**: JWT auth, RBAC, data isolation
15. **Scalable Design**: Supports multiple accounts, sites, and users
This architecture ensures scalability, maintainability, and extensibility while providing a robust foundation for the IGNY8 platform.

1644
master-docs/03-FRONTEND-ARCHITECTURE.md
View File

File diff suppressed because it is too large Load Diff

1268
master-docs/04-BACKEND-IMPLEMENTATION.md
View File

File diff suppressed because it is too large Load Diff

676
master-docs/05-AI-FRAMEWORK-IMPLEMENTATION.md
View File

@@ -1,676 +0,0 @@
# IGNY8 AI Framework Implementation Reference
**Last Updated:** 2025-01-XX (Added 3 missing AI functions: generate_site_structure, optimize_content, generate_page_content)
**Purpose:** Complete AI framework implementation reference covering architecture, code structure, all 8 AI functions, execution flow, progress tracking, cost tracking, prompt management, and model configuration.
---
## Table of Contents
1. [AI Framework Overview](#ai-framework-overview)
2. [Common Architecture](#common-architecture)
3. [AI Function Execution Flow](#ai-function-execution-flow)
4. [AI Functions](#ai-functions)
5. [Progress Tracking](#progress-tracking)
6. [Cost Tracking](#cost-tracking)
7. [Prompt Management](#prompt-management)
8. [Model Configuration](#model-configuration)
---
## AI Framework Overview
The IGNY8 AI framework provides a unified interface for all AI operations. All AI functions inherit from `BaseAIFunction` and are orchestrated by `AIEngine`, ensuring consistent execution, progress tracking, error handling, and cost tracking.
### Key Components
- **BaseAIFunction**: Abstract base class for all AI functions
- **AIEngine**: Central orchestrator managing lifecycle, progress, logging, cost tracking
- **AICore**: Centralized AI request handler for all AI operations
- **PromptRegistry**: Centralized prompt management with hierarchical resolution
- **Function Registry**: Lazy-loaded function registry
- **Progress Tracking**: Real-time progress updates via Celery
- **Cost Tracking**: Automatic cost and token tracking
### AI Functions
1. **Auto Cluster Keywords**: Group related keywords into semantic clusters
2. **Generate Ideas**: Generate content ideas from keyword clusters
3. **Generate Content**: Generate blog post and article content
4. **Generate Image Prompts**: Extract image prompts from content
5. **Generate Images**: Generate images using OpenAI DALL-E or Runware
6. **Generate Site Structure**: Create site/page architecture from business brief
7. **Optimize Content**: Optimize content for SEO, readability, and engagement
8. **Generate Page Content**: Generate structured page content with JSON blocks for Site Builder
---
## Common Architecture
### Core Framework Files
#### Entry Point
**File**: `backend/igny8_core/ai/tasks.py`
**Function**: `run_ai_task`
**Purpose**: Unified Celery task entrypoint for all AI functions
**Parameters**: `function_name` (str), `payload` (dict), `account_id` (int)
**Flow**: Loads function from registry → Creates AIEngine → Executes function
#### Engine Orchestrator
**File**: `backend/igny8_core/ai/engine.py`
**Class**: `AIEngine`
**Purpose**: Central orchestrator managing lifecycle, progress, logging, cost tracking
**Methods**:
- `execute` - Main execution pipeline (6 phases: INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
- `_handle_error` - Centralized error handling
- `_log_to_database` - Logs to AITaskLog model
#### Base Function Class
**File**: `backend/igny8_core/ai/base.py`
**Class**: `BaseAIFunction`
**Purpose**: Abstract base class defining interface for all AI functions
**Abstract Methods**:
- `get_name` - Returns function name (e.g., 'auto_cluster')
- `prepare` - Loads and prepares data
- `build_prompt` - Builds AI prompt
- `parse_response` - Parses AI response
- `save_output` - Saves results to database
**Optional Methods**:
- `get_metadata` - Returns display name, description, phases
- `get_max_items` - Returns max items limit (or None)
- `validate` - Validates input payload (default: checks for 'ids')
- `get_model` - Returns model override (default: None, uses account default)
#### Function Registry
**File**: `backend/igny8_core/ai/registry.py`
**Functions**:
- `register_function` - Registers function class
- `register_lazy_function` - Registers lazy loader
- `get_function` - Gets function class by name (lazy loads if needed)
- `get_function_instance` - Gets function instance by name
- `list_functions` - Lists all registered functions
**Registered Functions** (7 lazy-loaded):
1. `auto_cluster` - AutoClusterFunction
2. `generate_ideas` - GenerateIdeasFunction
3. `generate_content` - GenerateContentFunction
4. `generate_images` - GenerateImagesFunction
5. `generate_image_prompts` - GenerateImagePromptsFunction
6. `generate_site_structure` - GenerateSiteStructureFunction
7. `optimize_content` - OptimizeContentFunction
**Note**: `generate_page_content` exists as a function but may be called directly without registry registration.
#### AI Core Handler
**File**: `backend/igny8_core/ai/ai_core.py`
**Class**: `AICore`
**Purpose**: Centralized AI request handler for all AI operations (text and image generation)
**Methods**:
- `run_ai_request` - Makes API call to OpenAI/Runware for text generation
- `generate_image` - Makes API call to OpenAI DALL-E or Runware for image generation
- `extract_json` - Extracts JSON from response (handles markdown code blocks)
#### Prompt Registry
**File**: `backend/igny8_core/ai/prompts.py`
**Class**: `PromptRegistry`
**Purpose**: Centralized prompt management with hierarchical resolution
**Method**: `get_prompt` - Gets prompt with resolution order:
1. Task-level prompt_override (if exists)
2. DB prompt for (account, function)
3. Default fallback from DEFAULT_PROMPTS registry
**Prompt Types**:
- `clustering` - For auto_cluster function
- `ideas` - For generate_ideas function
- `content_generation` - For generate_content function
- `image_prompt_extraction` - For extract_image_prompts function
- `image_prompt_template` - Template for formatting image prompts
- `negative_prompt` - Negative prompt for Runware image generation
- `site_structure_generation` - For generate_site_structure function
- `content_optimization` - For optimize_content function
- `page_content_generation` - For generate_page_content function
#### Model Settings
**File**: `backend/igny8_core/ai/settings.py`
**Constants**: `FUNCTION_ALIASES` - Function name aliases for backward compatibility
**Functions**:
- `get_model_config(function_name, account)` - Gets model config from IntegrationSettings (account required, no fallbacks)
- Raises `ValueError` if IntegrationSettings not configured
- Returns dict with `model`, `max_tokens`, `temperature`, `response_format`
---
## AI Function Execution Flow
### Complete Execution Pipeline
```
1. API Endpoint (views.py)
↓
2. run_ai_task (tasks.py)
- Gets account from account_id
- Gets function instance from registry
- Creates AIEngine
↓
3. AIEngine.execute (engine.py)
Phase 1: INIT (0-10%)
- Calls function.validate()
- Updates progress tracker
↓
Phase 2: PREP (10-25%)
- Calls function.prepare()
- Calls function.build_prompt()
- Updates progress tracker
↓
Phase 3: AI_CALL (25-70%)
- Gets model config from settings
- Calls AICore.run_ai_request() or AICore.generate_image()
- Tracks cost and tokens
- Updates progress tracker
↓
Phase 4: PARSE (70-85%)
- Calls function.parse_response()
- Updates progress tracker
↓
Phase 5: SAVE (85-98%)
- Calls function.save_output()
- Logs credit usage
- Updates progress tracker
↓
Phase 6: DONE (98-100%)
- Logs to AITaskLog
- Returns result
```
### Progress Updates
**Progress Endpoint**: `/api/v1/system/settings/task_progress/{task_id}/`
**Response Format**:
- `state`: Task state (PENDING, PROGRESS, SUCCESS, FAILURE)
- `meta`: Progress metadata
- `phase`: Current phase (INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
- `percentage`: Progress percentage (0-100)
- `message`: User-friendly message
- `request_steps`: Array of request steps
- `response_steps`: Array of response steps
- `cost`: API cost in USD
- `tokens`: Token count
---
## AI Functions
### 1. Auto Cluster Keywords
**Purpose**: Group related keywords into semantic clusters using AI
**Function Class**: `AutoClusterFunction`
**File**: `backend/igny8_core/ai/functions/auto_cluster.py`
**API Endpoint**:
- **ViewSet**: `KeywordViewSet`
- **Action**: `auto_cluster`
- **Method**: POST
- **URL Path**: `/v1/planner/keywords/auto_cluster/`
- **Payload**: `ids` (list[int]) - Keyword IDs
**Function Methods**:
- `get_name()`: Returns `'auto_cluster'`
- `validate(payload, account)`: Validates keyword IDs exist
- `prepare(payload, account)`: Loads keywords from database
- `build_prompt(data, account)`: Builds clustering prompt with keyword data
- `parse_response(response, step_tracker)`: Parses cluster JSON response
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Creates Cluster records and links keywords
**Input**: List of keyword IDs
**Output**: Cluster records created, keywords linked to clusters
**Progress Messages**:
- INIT: "Validating keywords"
- PREP: "Preparing keyword clustering"
- AI_CALL: "Analyzing keyword relationships"
- PARSE: "Processing cluster data"
- SAVE: "Creating clusters"
### 2. Generate Ideas
**Purpose**: Generate content ideas from keyword clusters
**Function Class**: `GenerateIdeasFunction`
**File**: `backend/igny8_core/ai/functions/generate_ideas.py`
**API Endpoint**:
- **ViewSet**: `ClusterViewSet`
- **Action**: `auto_generate_ideas`
- **Method**: POST
- **URL Path**: `/v1/planner/clusters/auto_generate_ideas/`
- **Payload**: `ids` (list[int]) - Cluster IDs
**Function Methods**:
- `get_name()`: Returns `'generate_ideas'`
- `validate(payload, account)`: Validates cluster IDs exist
- `prepare(payload, account)`: Loads clusters and keywords
- `build_prompt(data, account)`: Builds idea generation prompt with cluster data
- `parse_response(response, step_tracker)`: Parses ideas JSON response
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Creates ContentIdeas records
**Input**: List of cluster IDs
**Output**: ContentIdeas records created
**Progress Messages**:
- INIT: "Verifying cluster integrity"
- PREP: "Loading cluster keywords"
- AI_CALL: "Generating ideas with Igny8 Semantic AI"
- PARSE: "{count} high-opportunity idea(s) generated"
- SAVE: "Content Outline for Ideas generated"
### 3. Generate Content
**Purpose**: Generate blog post and article content from tasks
**Function Class**: `GenerateContentFunction`
**File**: `backend/igny8_core/ai/functions/generate_content.py`
**API Endpoint**:
- **ViewSet**: `TasksViewSet`
- **Action**: `auto_generate_content`
- **Method**: POST
- **URL Path**: `/v1/writer/tasks/auto_generate_content/`
- **Payload**: `ids` (list[int]) - Task IDs (max 50)
**Function Methods**:
- `get_name()`: Returns `'generate_content'`
- `get_max_items()`: Returns `50` (max tasks per batch)
- `validate(payload, account)`: Validates task IDs exist
- `prepare(payload, account)`: Loads tasks with related data
- `build_prompt(data, account)`: Builds content generation prompt with task data
- `parse_response(response, step_tracker)`: Parses content (JSON or plain text)
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Creates/updates Content records
**Input**: List of task IDs
**Output**: Content records created/updated with HTML content
**Progress Messages**:
- INIT: "Initializing content generation"
- PREP: "Loading tasks and building prompts"
- AI_CALL: "Generating content with AI"
- PARSE: "Processing content"
- SAVE: "Saving content"
### 4. Generate Image Prompts
**Purpose**: Extract image prompts from content for generating images
**Function Class**: `GenerateImagePromptsFunction`
**File**: `backend/igny8_core/ai/functions/generate_image_prompts.py`
**API Endpoint**:
- **ViewSet**: `TasksViewSet` (via content)
- **Action**: `generate_image_prompts`
- **Method**: POST
- **URL Path**: `/v1/writer/content/generate_image_prompts/`
- **Payload**: `ids` (list[int]) - Content IDs
**Function Methods**:
- `get_name()`: Returns `'generate_image_prompts'`
- `validate(payload, account)`: Validates content IDs exist
- `prepare(payload, account)`: Loads content records
- `build_prompt(data, account)`: Builds prompt extraction prompt with content HTML
- `parse_response(response, step_tracker)`: Parses image prompts JSON
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Updates Images records with prompts
**Input**: List of content IDs
**Output**: Images records updated with prompts (featured, in-article)
**Progress Messages**:
- INIT: "Validating content"
- PREP: "Preparing image prompt extraction"
- AI_CALL: "Extracting image prompts"
- PARSE: "Processing image prompts"
- SAVE: "Saving image prompts"
### 5. Generate Images
**Purpose**: Generate images using AI (OpenAI DALL-E or Runware) based on prompts
**Function Class**: `GenerateImagesFunction`
**File**: `backend/igny8_core/ai/functions/generate_images.py`
**API Endpoint**:
- **ViewSet**: `ImagesViewSet`
- **Action**: `generate_images`
- **Method**: POST
- **URL Path**: `/v1/writer/images/generate_images/`
- **Payload**: `ids` (list[int]) - Image IDs
**Function Methods**:
- `get_name()`: Returns `'generate_images'`
- `validate(payload, account)`: Validates image IDs exist and have prompts
- `prepare(payload, account)`: Loads images with prompts
- `build_prompt(data, account)`: Formats image prompt with context
- `parse_response(response, step_tracker)`: Parses image URL from API response
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Updates Images records with image URLs
**Input**: List of image IDs (with prompts)
**Output**: Images records updated with image URLs
**Image Generation Settings**:
- Provider: 'openai' or 'runware'
- Model: Model name (e.g., 'dall-e-3', 'runware:97@1')
- Image Type: 'realistic', 'artistic', 'cartoon'
- Max In-Article Images: Max images per content
- Image Format: 'webp', 'jpg', 'png'
- Desktop/Mobile: Boolean flags
**Progress Messages**:
- INIT: "Validating image prompts"
- PREP: "Preparing image generation"
- AI_CALL: "Creating image(s) with AI"
- PARSE: "Processing image response"
- SAVE: "Saving generated image(s)"
### 6. Generate Site Structure
**Purpose**: Create site/page architecture from business brief, objectives, and style guides
**Function Class**: `GenerateSiteStructureFunction`
**File**: `backend/igny8_core/ai/functions/generate_site_structure.py`
**API Endpoint**:
- **ViewSet**: `SiteBlueprintViewSet`
- **Action**: `generate_structure`
- **Method**: POST
- **URL Path**: `/v1/site-builder/blueprints/{id}/generate_structure/`
- **Payload**: `ids` (list[int]) - Site Blueprint IDs
**Function Methods**:
- `get_name()`: Returns `'generate_site_structure'`
- `validate(payload, account)`: Validates blueprint ID exists
- `prepare(payload, account)`: Loads site blueprint with related data
- `build_prompt(data, account)`: Builds site structure generation prompt with business brief, objectives, style guides
- `parse_response(response, step_tracker)`: Parses site structure JSON (pages, blocks, navigation)
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Creates PageBlueprint records with blocks
**Input**: Site Blueprint ID
**Output**: PageBlueprint records created with structured blocks
**Progress Messages**:
- INIT: "Validating blueprint data…"
- PREP: "Preparing site context…"
- AI_CALL: "Generating site structure with AI…"
- PARSE: "Parsing generated blueprint…"
- SAVE: "Saving pages and blocks…"
- DONE: "Site structure ready!"
### 7. Optimize Content
**Purpose**: Optimize content for SEO, readability, and engagement
**Function Class**: `OptimizeContentFunction`
**File**: `backend/igny8_core/ai/functions/optimize_content.py`
**API Endpoint**:
- **ViewSet**: `OptimizerViewSet`
- **Action**: `optimize` or `analyze`
- **Method**: POST
- **URL Path**: `/v1/optimizer/optimize/` or `/v1/optimizer/analyze/`
- **Payload**: `ids` (list[int]) - Content IDs, `entry_point` (optional, str)
**Function Methods**:
- `get_name()`: Returns `'optimize_content'`
- `validate(payload, account)`: Validates content IDs exist
- `prepare(payload, account)`: Loads content with related data
- `build_prompt(data, account)`: Builds optimization prompt with content, SEO targets, readability goals
- `parse_response(response, step_tracker)`: Parses optimized content JSON
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Updates Content records with optimized content and scores
**Input**: List of content IDs
**Output**: Content records updated with optimized content, SEO scores, readability scores
**Optimization Features**:
- SEO optimization (keyword density, meta descriptions, headings)
- Readability improvements (sentence length, paragraph structure)
- Engagement enhancements (call-to-actions, internal links)
- Content scoring (SEO score, readability score, engagement score)
**Progress Messages**:
- INIT: "Validating content data…"
- PREP: "Preparing content context…"
- AI_CALL: "Optimizing content with AI…"
- PARSE: "Parsing optimized content…"
- SAVE: "Saving optimized content…"
- DONE: "Content optimized!"
### 8. Generate Page Content
**Purpose**: Generate structured page content with JSON blocks for Site Builder pages
**Function Class**: `GeneratePageContentFunction`
**File**: `backend/igny8_core/ai/functions/generate_page_content.py`
**API Endpoint**:
- **ViewSet**: `PageBlueprintViewSet`
- **Action**: `generate_content` or `regenerate`
- **Method**: POST
- **URL Path**: `/v1/site-builder/pages/{id}/generate_content/` or `/v1/site-builder/pages/{id}/regenerate/`
- **Payload**: `ids` (list[int]) - Page Blueprint IDs (max 20)
**Function Methods**:
- `get_name()`: Returns `'generate_page_content'`
- `get_max_items()`: Returns `20` (max pages per batch)
- `validate(payload, account)`: Validates page blueprint IDs exist
- `prepare(payload, account)`: Loads page blueprints with related data
- `build_prompt(data, account)`: Builds page content generation prompt optimized for Site Builder
- `parse_response(response, step_tracker)`: Parses JSON blocks format
- `save_output(parsed, original_data, account, progress_tracker, step_tracker)`: Updates PageBlueprint records with blocks_json
**Input**: List of page blueprint IDs
**Output**: PageBlueprint records updated with structured blocks_json
**Key Differences from Generate Content**:
- Outputs structured JSON blocks format instead of HTML
- Optimized prompts for site builder pages
- Supports page-specific context (site structure, navigation, related pages)
- Blocks can include: headings, paragraphs, images, CTAs, forms, etc.
**Progress Messages**:
- INIT: "Initializing page content generation..."
- PREP: "Loading page blueprint and building prompt..."
- AI_CALL: "Generating structured content with AI..."
- PARSE: "Parsing JSON blocks..."
- SAVE: "Saving blocks to page..."
- DONE: "Page content generated!"
---
## Progress Tracking
### Progress Phases
All AI functions follow the same 6-phase execution:
1. **INIT** (0-10%): Validation phase
2. **PREP** (10-25%): Data preparation phase
3. **AI_CALL** (25-70%): AI API call phase
4. **PARSE** (70-85%): Response parsing phase
5. **SAVE** (85-98%): Database save phase
6. **DONE** (98-100%): Completion phase
### Progress Updates
**Frontend Polling**: Frontend polls `/api/v1/system/settings/task_progress/{task_id}/` every 1-2 seconds
**Progress Response**:
- `state`: Task state
- `meta`: Progress metadata
- `phase`: Current phase
- `percentage`: Progress percentage
- `message`: User-friendly message
- `request_steps`: Request steps array
- `response_steps`: Response steps array
- `cost`: API cost
- `tokens`: Token count
### Step Tracking
**Request Steps**: Tracked during prompt building and AI call
**Response Steps**: Tracked during response parsing
**Purpose**: Provides detailed logging for debugging and transparency
---
## Cost Tracking
### Cost Calculation
**Text Generation**:
- Cost calculated based on model pricing (input tokens + output tokens)
- Tracked per request
- Stored in `CostTracker`
**Image Generation**:
- Cost calculated based on provider pricing
- OpenAI DALL-E: Fixed cost per image
- Runware: Variable cost per image
- Tracked per image
### Cost Storage
**AITaskLog Model**:
- `cost`: Total cost for task
- `tokens`: Total tokens used
**CreditUsageLog Model**:
- `cost_usd`: Cost in USD
- `credits_used`: Credits deducted
---
## Prompt Management
### Prompt Resolution Order
1. **Task-Level Override**: If task has `prompt_override`, use it
2. **Database Prompt**: If account has custom prompt in database, use it
3. **Default Prompt**: Use default prompt from `DEFAULT_PROMPTS` registry
### Prompt Customization
**Per Account**: Custom prompts stored in `AIPrompt` model
**Per Function**: Different prompts for each function type
**Context Variables**: Prompts support context placeholders:
- `[IGNY8_KEYWORDS]` - Keyword list
- `[IGNY8_CLUSTERS]` - Cluster list
- `[IGNY8_CLUSTER_KEYWORDS]` - Cluster keywords
- `[IGNY8_IDEA]` - Idea data
- `[IGNY8_CLUSTER]` - Cluster data
---
## Model Configuration
### IntegrationSettings - Single Source of Truth
**IMPORTANT**: As of the refactoring completed in 2025-01-XX, the AI framework uses **IntegrationSettings only** for model configuration. There are no hardcoded defaults or fallbacks.
**IntegrationSettings Model**:
- `integration_type`: 'openai' or 'runware' (required)
- `account`: Account instance (required) - each account must configure their own models
- `is_active`: Boolean (must be True for configuration to be used)
- `config`: JSONField with model configuration (required)
- `model`: Model name (required) - e.g., 'gpt-4o-mini', 'gpt-4o', 'dall-e-3'
- `max_tokens`: Max tokens (optional, defaults to 4000)
- `temperature`: Temperature (optional, defaults to 0.7)
- `response_format`: Response format (optional, automatically set for JSON mode models)
### Model Configuration Function
**File**: `backend/igny8_core/ai/settings.py`
**Function**: `get_model_config(function_name: str, account) -> Dict[str, Any]`
**Behavior**:
- **Requires** `account` parameter (no longer optional)
- **Requires** IntegrationSettings to be configured for the account
- **Raises** `ValueError` with clear error messages if:
- Account not provided
- IntegrationSettings not found for account
- Model not configured in IntegrationSettings
- IntegrationSettings is inactive
**Error Messages**:
- Missing account: `"Account is required for model configuration"`
- Missing IntegrationSettings: `"OpenAI IntegrationSettings not configured for account {id}. Please configure OpenAI settings in the integration page."`
- Missing model: `"Model not configured in IntegrationSettings for account {id}. Please set 'model' in OpenAI integration settings."`
**Returns**:
```python
{
'model': str, # Model name from IntegrationSettings
'max_tokens': int, # From config or default 4000
'temperature': float, # From config or default 0.7
'response_format': dict, # JSON mode for supported models, or None
}
```
### Account-Specific Configuration
**Key Principle**: Each account must configure their own AI models. There are no global defaults.
**Configuration Steps**:
1. Navigate to Settings → Integrations
2. Configure OpenAI integration settings
3. Set `model` in the configuration (required)
4. Optionally set `max_tokens` and `temperature`
5. Ensure integration is active
**Supported Models**:
- Text generation: `gpt-4o-mini`, `gpt-4o`, `gpt-4-turbo`, etc.
- Image generation: `dall-e-3` (OpenAI) or `runware:97@1` (Runware)
- JSON mode: Automatically enabled for supported models (gpt-4o, gpt-4-turbo, etc.)
### Function Aliases
**File**: `backend/igny8_core/ai/settings.py`
**FUNCTION_ALIASES**: Dictionary mapping legacy function names to current names
- `cluster_keywords` → `auto_cluster`
- `auto_cluster_keywords` → `auto_cluster`
- `auto_generate_ideas` → `generate_ideas`
- `auto_generate_content` → `generate_content`
- `auto_generate_images` → `generate_images`
**Purpose**: Maintains backward compatibility with legacy function names.
### Removed Functions
The following helper functions were removed as part of the refactoring (they were never used):
- `get_model()` - Removed (use `get_model_config()['model']` instead)
- `get_max_tokens()` - Removed (use `get_model_config()['max_tokens']` instead)
- `get_temperature()` - Removed (use `get_model_config()['temperature']` instead)
**Rationale**: These functions were redundant - `get_model_config()` already returns all needed values.
---
## Summary
The IGNY8 AI framework provides:
1. **Unified Interface**: All AI functions use the same execution pipeline
2. **Consistent Execution**: All functions follow the same 6-phase flow
3. **Progress Tracking**: Real-time progress updates via Celery
4. **Cost Tracking**: Automatic cost and token tracking
5. **Error Handling**: Centralized error handling in AIEngine
6. **Prompt Management**: Hierarchical prompt resolution
7. **Model Configuration**: Per-account model overrides
8. **Database Logging**: Automatic logging to AITaskLog
9. **Extensibility**: Easy to add new AI functions
10. **Reliability**: Retry logic and error recovery
11. **8 AI Functions**: Complete coverage from planning to publishing
12. **Site Builder Integration**: Specialized functions for site structure and page content
13. **Content Optimization**: AI-powered content optimization and scoring
This architecture ensures consistency, maintainability, and extensibility while providing a robust foundation for all AI operations in the IGNY8 platform, supporting 8 AI functions across the complete content workflow.

1395
master-docs/06-FUNCTIONAL-BUSINESS-LOGIC.md
View File

File diff suppressed because it is too large Load Diff

156
master-docs/AGENT_MASTER_REFERENCE.md
View File

@@ -1,156 +0,0 @@
# Agent Master Reference — IGNY8
Purpose: provide a single, navigable reference for any new agent (human or automated) to locate the exact files, entry points, and functional responsibilities across the IGNY8 monorepo. Use this as the starting point for feature work, bug fixes, or integrations.
Contents
- Repository snapshot (concise tree)
- Key modules & responsibilities (table)
- Important functions / entrypoints (table)
- Quick agent workflow (5 steps)
- Setup & common commands
---
**Repository Snapshot (Top-level, concise)**
- `backend/` : Django project and related management scripts
- `manage.py` : Django CLI entry
- `requirements.txt` : Python deps
- `igny8_core/` : main Django package
- `settings.py`, `asgi.py`, `wsgi.py`, `celery.py`
- `api/`, `ai/`, `auth/`, `admin/`, `business/`, `modules/`, `utils/`
- `frontend/` (legacy frontend bundle inside backend)
- `frontend/` : Vite + React application (modern front-end)
- `package.json`, `vite.config.ts`, `src/` (React + TS), `public/`
- `master-docs/` : documentation; authoritative notes about architecture
- `docker-compose.app.yml` : local dev stack (DB, cache, web, worker)
---
**Key Modules & Purpose**
| Module / Path | Purpose / Responsibility | Quick Notes |
|---|---|---|
| `backend/manage.py` | Django management entrypoint | Run migrations, tests, server |
| `igny8_core/settings.py` | Central config for Django | Env-driven; source of secrets/flags |
| `igny8_core/celery.py` | Celery app configuration | Worker + beat scheduling setup |
| `igny8_core/ai/` | AI orchestration layer | Models and engine integration |
| `igny8_core/api/` | REST endpoints for backend | Look here for API implementations |
| `frontend/` | Modern frontend app | `src/` contains components, hooks, services |
| `docker-compose.app.yml` | Local dev orchestration | DB, cache, web, worker definitions |
| `master-docs/` | Documentation and process| Use for architecture decisions and public docs |
---
**Important Files & Entrypoints (where to start for common tasks)**
| Task | File / Function | Where to look |
|---|---|---|
| Start backend locally | `backend/manage.py` | `python manage.py runserver` (see file for settings) |
| Celery worker/beat | `igny8_core/celery.py` | `celery -A igny8_core worker` and `celery -A igny8_core beat` |
| Add/inspect REST endpoint | `igny8_core/api/` | Search for view classes or `@api_view` functions |
| AI model orchestration | `igny8_core/ai/engine.py` (or `ai_core.py`) | See `05-AI-FRAMEWORK-IMPLEMENTATION.md` in `master-docs/` |
| Frontend page/component | `frontend/src/pages/` and `frontend/src/components/` | Use the `App` and route files in `src/` |
---
**Function / Area Quick-Reference (examples)**
- Celery and periodic tasks
- File: `igny8_core/celery.py`
- Purpose: configure Celery app, load periodic tasks (beat schedule is present at `backend/celerybeat-schedule`).
- AI orchestration
- Files: `igny8_core/ai/ai_core.py`, `igny8_core/ai/engine.py` (or similarly named)
- Purpose: implement model selection, prompt orchestration, caching, and engine interfaces.
- API handlers
- Path: `igny8_core/api/` (search for submodules per resource)
- Purpose: HTTP endpoints used by `frontend/` and external integrations.
- Frontend data services
- Path: `frontend/src/services/` and `frontend/src/api/`
- Purpose: client-side API wrappers; coordinate expected backend response shapes.
---
**Agent Quick Workflow — 5 Steps**
1. Identify the feature or bug area
- Use this reference to map the user-facing feature to `frontend/` pages and `igny8_core/api/` endpoints.
- Search for the route or identifiable component in `frontend/src/`.
2. Locate the backend API handler
- From the frontend service or API call, open the corresponding URL and find the view in `igny8_core/api/`.
- Inspect serializer, view, and model (if present) in the same directory.
3. Check configuration and environment
- Open `igny8_core/settings.py` to find related flags and env vars.
- For scheduled/background work, inspect `igny8_core/celery.py` and `backend/celerybeat-schedule`.
4. Implement change and run local checks
- Backend: create/modify files under `igny8_core/` and run `python manage.py test` or `pytest` as configured.
- Frontend: modify `frontend/src/` and run `npm run dev` or `npm run build` for production checks.
5. Update documentation & tests
- Add or update `master-docs/*` when making cross-cutting changes.
- Update the `API-COMPLETE-REFERENCE.md` if API shapes change.
---
**Common Commands (PowerShell-friendly)**
Backend setup and run (PowerShell):
```
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
```
Run Celery worker/beat (PowerShell):
```
cd backend
.\.venv\Scripts\Activate.ps1
celery -A igny8_core worker -l info
celery -A igny8_core beat -l info
```
Frontend dev (Windows PowerShell):
```
cd frontend
npm install
npm run dev
```
Docker compose local stack:
```
docker-compose -f docker-compose.app.yml up --build
```
---
**Guidance for new agents**
- Always cross-check `master-docs/` entries when making architectural changes.
- When changing an API, update `master-docs/API-COMPLETE-REFERENCE.md` and the frontend wrappers in `frontend/src/services/`.
- For AI changes, refer to `master-docs/05-AI-FRAMEWORK-IMPLEMENTATION.md` before editing `igny8_core/ai/`.
---
If you want, I can:
- Expand the file tree to include all files per directory (full tree).
- Generate a CSV or JSON mapping of file → responsibilities for programmatic use.
- Add an index of search terms and likely filenames for quick grep commands.
End of reference.

193
master-docs/CURRENT_WORKFLOW_STATUS.md
View File

@@ -1,193 +0,0 @@
# IGNY8 Current Workflow Status
**Last Updated:** 2025-01-XX
**Purpose:** Single source of truth for current system state, active work, and recent changes
---
## Current System State
### Workflow Path (Current)
```
PLANNING → WRITER → OPTIMIZE → PUBLISH
```
**Direct Path:** Keywords/Clusters → Ideas → Tasks → Content (no wizard intermediary)
### Removed Features (2025-11-20)
- **Site Builder Wizard** - 6-step guided wizard process completely removed
- **WorkflowState Model** - Backend model and services removed
- **Wizard Routes** - `/sites/builder`, `/sites/builder/preview`, `/sites/blueprints` routes removed
- **Wizard UI Components** - All wizard step components removed from frontend
### Active Features
- ✅ **Site Blueprint APIs** - All backend APIs for creating/managing blueprints still work
- ✅ **Site Builder Models** - SiteBlueprint, PageBlueprint, SiteBlueprintCluster, SiteBlueprintTaxonomy models active
- ✅ **Direct Workflow** - Users can go directly from Planning → Writer → Optimize → Publish
- ✅ **All Core Modules** - Planner, Writer, Optimizer, Publisher all functional
---
## Recent Changes
### Site Builder Wizard Removal (2025-11-20)
**What Was Deleted:**
#### Frontend Files
- `/frontend/src/pages/Sites/Builder/Wizard.tsx`
- `/frontend/src/pages/Sites/Builder/Preview.tsx`
- `/frontend/src/pages/Sites/Builder/Blueprints.tsx`
- All wizard step components (`steps/*.tsx`)
- Wizard components (`components/WizardProgress.tsx`, `components/HelperDrawer.tsx`)
- `/frontend/src/store/builderStore.ts`
#### Backend Files
- `/backend/igny8_core/business/site_building/services/workflow_state_service.py`
- `/backend/igny8_core/business/site_building/services/wizard_context_service.py`
- `/backend/igny8_core/business/site_building/services/validators.py`
#### Backend Model
- `WorkflowState` model removed from `models.py`
#### Database
- Table: `igny8_site_blueprint_workflow_states` (dropped)
### Leftover Code Cleanup (2025-01-XX)
**Additional Cleanup Completed:**
#### Frontend API Functions Removed
- `fetchWizardContext()` - Called non-existent `/workflow/context/` endpoint
- `updateWorkflowStep()` - Called non-existent `/workflow/step/` endpoint
#### TypeScript Interfaces Removed
- `WorkflowState` interface - No longer needed (model removed)
- `WizardContext` interface - No longer needed (wizard removed)
- `workflow_state` field removed from `SiteBlueprint` interface
#### Frontend Components Fixed
- **Planner Dashboard** (`frontend/src/pages/Planner/Dashboard.tsx`):
- Removed `incompleteBlueprints` state and filtering logic
- Removed incomplete workflows alert banner
- Removed unused `Alert` import
**Files Modified:**
1. `frontend/src/services/api.ts` - Removed wizard/workflow functions and interfaces
2. `frontend/src/pages/Planner/Dashboard.tsx` - Removed workflow state references
**Status:** ✅ All leftover wizard/workflow code has been cleaned up
---
## What's Still Active (Site Builder)
### Models Still Active
1. **SiteBlueprint** (`igny8_site_blueprints`)
2. **PageBlueprint** (`igny8_page_blueprints`)
3. **SiteBlueprintCluster** (`igny8_site_blueprint_clusters`)
4. **SiteBlueprintTaxonomy** (`igny8_site_blueprint_taxonomies`)
5. **BusinessType** (`igny8_site_builder_business_types`)
6. **AudienceProfile** (`igny8_site_builder_audience_profiles`)
7. **BrandPersonality** (`igny8_site_builder_brand_personalities`)
8. **HeroImageryDirection** (`igny8_site_builder_hero_imagery`)
### API Endpoints Still Available
- `GET/POST /api/v1/site-builder/blueprints/`
- `GET/POST /api/v1/site-builder/pages/`
- `POST /api/v1/site-builder/blueprints/{id}/generate_structure/`
- `POST /api/v1/site-builder/blueprints/{id}/generate_all_pages/`
- `POST /api/v1/site-builder/blueprints/{id}/clusters/attach`
- `POST /api/v1/site-builder/blueprints/{id}/taxonomies/`
- `GET /api/v1/site-builder/metadata/`
### Services Still Active
- `StructureGenerationService` - AI structure generation
- `PageGenerationService` - Page content generation
- `TaxonomyService` - Taxonomy management
- `SiteBuilderFileService` - File management
---
## Migration & Database State
### Migration State
- All apps have single `0001_initial.py` migrations
- Clean migration state (no migration history)
- Database structure matches current models
- WorkflowState table removed from database
### Database Backup
- **Backup:** `backup_postgres_20251120_232816.sql` (646KB)
- Contains all data except WorkflowState (intentionally excluded)
---
## Current Workflow Details
### Site Setup & Integration (New Flow)
#### Step 1: Add Site (WordPress)
- User adds a new WordPress site from the welcome screen or sites page
- During site creation, user selects:
- **Industry**: From available industries (e.g., Technology, Healthcare, Finance)
- **Sectors**: Multiple sectors within the selected industry (e.g., SaaS, E-commerce, Mobile Apps)
- **Site Name**: Display name for the site
- **Website Address**: WordPress site URL
- Site is created with industry and sectors already configured
#### Step 2: Integrate Site
- User is redirected to Site Settings → Integrations tab (`/sites/{id}/settings?tab=integrations`)
- **API Key Generation**:
- User generates a unique API key for the site
- API key is displayed and can be copied
- Key is stored securely in the integration credentials
- **Plugin Download**:
- User downloads the IGNY8 WP Bridge plugin directly from the page
- Plugin provides deeper WordPress integration than default WordPress app
- **WordPress Configuration**:
- User enters WordPress site URL
- User enters WordPress username
- User enters Application Password (created in WordPress admin)
- User enables/disables integration and two-way sync
- Integration is saved and connection is tested
### Phase 1: Planning
- Keyword import and management
- Auto-clustering (1 credit per 30 keywords)
- Content idea generation (1 credit per idea)
- Queue ideas to Writer
### Phase 2: Writer
- Task creation from ideas
- Content generation (3 credits per content)
- Image generation (1 credit per image)
- Content review and editing
### Phase 3: Optimize
- Internal linking suggestions
- Content optimization scoring
- Apply improvements
### Phase 4: Publish
- WordPress publishing (via IGNY8 WP Bridge plugin)
- Site deployment (for IGNY8-hosted sites)
- Content validation
---
## Notes
- Site blueprints can still be created/managed through API endpoints
- No guided UI wizard available
- Direct path from Planning to Writer is the standard workflow
- All core functionality remains intact
---
**Last Updated:** 2025-01-XX
**Status:** Current and Active

BIN
master-docs/file-tree.md
View File

Binary file not shown.