diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..79243a0f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,207 @@ +# IGNY8 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. + +--- + +## 📋 Changelog Management + +**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: +- **Version**: Semantic versioning (MAJOR.MINOR.PATCH) +- **Date**: YYYY-MM-DD 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 +- (No unreleased features) + +### Changed +- (No unreleased changes) + +### Fixed +- (No unreleased fixes) + +--- + +## [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 + +#### 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 + +### Documentation + +#### 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 + +#### Documentation Features +- Complete workflow documentation +- Feature completeness +- No code snippets (workflow-focused) +- Accurate state reflection +- Cross-referenced documents +- Self-explaining structure for AI agents + +--- + +## 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. + +--- + +## Planned Features + +### In Progress +- Planner Dashboard enhancement with KPIs +- Automation & CRON tasks +- Advanced analytics + +### Future +- Analytics module enhancements +- Advanced scheduling features +- Additional AI model integrations +- Stripe payment integration +- Plan limits enforcement +- Rate limiting +- Advanced reporting +- Mobile app support + +--- + +## Notes + +- 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. diff --git a/README.md b/README.md index 605ac334..b2ec5a4d 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,60 @@ # IGNY8 Platform -Full-stack SEO keyword management platform built with Django REST Framework and React. +Full-stack SaaS platform for SEO keyword management and AI-driven content generation, built with Django REST Framework and React. + +**Last Updated:** 2025-01-XX + +--- ## 🏗️ Architecture -- **Backend**: Django + DRF (Port 8010/8011) -- **Frontend**: React + TypeScript + Vite (Port 5173/8021) -- **Database**: PostgreSQL +- **Backend**: Django 5.2+ with Django REST Framework (Port 8010/8011) +- **Frontend**: React 19 with TypeScript and Vite (Port 5173/8021) +- **Database**: PostgreSQL 15 +- **Task Queue**: Celery with Redis - **Reverse Proxy**: Caddy (HTTPS on port 443) +- **Deployment**: Docker-based containerization -## 📁 Structure +## 📁 Project Structure ``` igny8/ ├── backend/ # Django backend │ ├── igny8_core/ # Django project -│ │ └── modules/ # Feature modules -│ │ └── planner/ # Keywords management module +│ │ ├── modules/ # Feature modules (Planner, Writer, System, Billing, Auth) +│ │ ├── ai/ # AI framework +│ │ ├── api/ # API base classes +│ │ └── middleware/ # Custom middleware │ ├── Dockerfile │ └── requirements.txt ├── frontend/ # React frontend │ ├── src/ -│ │ ├── pages/ # Page components -│ │ │ └── Planner/Keywords.tsx -│ │ ├── services/ # API clients -│ │ └── components/ # UI components +│ │ ├── pages/ # Page components +│ │ ├── services/ # API clients +│ │ ├── components/ # UI components +│ │ ├── config/ # Configuration files +│ │ └── stores/ # Zustand stores │ ├── Dockerfile -│ ├── Dockerfile.dev # Development mode +│ ├── Dockerfile.dev # Development mode │ └── vite.config.ts +├── docs/ # Complete documentation +│ ├── 00-DOCUMENTATION-MANAGEMENT.md # Documentation & changelog management (READ FIRST) +│ ├── 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 +├── CHANGELOG.md # Version history and changes (only updated after user confirmation) └── docker-compose.app.yml ``` +--- + ## 🚀 Quick Start ### Prerequisites + - Docker & Docker Compose - Node.js 18+ (for local development) - Python 3.11+ (for local development) @@ -77,69 +98,232 @@ docker build -f frontend/Dockerfile.dev -t igny8-frontend-dev ./frontend docker-compose -f docker-compose.app.yml up ``` +For complete installation guide, see [docs/01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md). + +--- + ## 📚 Features ### ✅ Implemented + - **Foundation**: Multi-tenancy system, Authentication (login/register), RBAC permissions -- **Planner Module**: Keywords, Clusters, Content Ideas (full CRUD, filtering, pagination, bulk operations, CSV import/export) -- **Writer Module**: Tasks, Content, Images (full CRUD, content generation, image generation) +- **Planner Module**: Keywords, Clusters, Content Ideas (full CRUD, filtering, pagination, bulk operations, CSV import/export, AI clustering) +- **Writer Module**: Tasks, Content, Images (full CRUD, AI content generation, AI image generation) - **Thinker Module**: Prompts, Author Profiles, Strategies, Image Testing - **System Module**: Settings, Integrations (OpenAI, Runware), AI Prompts - **Billing Module**: Credits, Transactions, Usage Logs - **AI Functions**: 5 AI operations (Auto Cluster, Generate Ideas, Generate Content, Generate Image Prompts, Generate Images) - **Frontend**: Complete component library, 4 master templates, config-driven UI system - **Backend**: REST API with tenant isolation, Site > Sector hierarchy, Celery async tasks +- **WordPress Integration**: Direct publishing to WordPress sites - **Development**: Docker Compose setup, hot reload, TypeScript + React ### 🚧 In Progress + - Planner Dashboard enhancement with KPIs -- WordPress integration (publishing) - Automation & CRON tasks +- Advanced analytics ### 🔄 Planned + - Analytics module enhancements - Advanced scheduling features - Additional AI model integrations +--- + ## 🔗 API Endpoints - **Planner**: `/api/v1/planner/keywords/`, `/api/v1/planner/clusters/`, `/api/v1/planner/ideas/` - **Writer**: `/api/v1/writer/tasks/`, `/api/v1/writer/images/` - **System**: `/api/v1/system/settings/` - **Billing**: `/api/v1/billing/` +- **Auth**: `/api/v1/auth/` - **Admin**: `/admin/` -See `docs/04-BACKEND.md` for complete API reference. +See [docs/04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) for complete API reference. + +--- ## 📖 Documentation -All documentation is consolidated in the `/docs/` folder. Start with `docs/README.md` for the complete documentation index. +All documentation is consolidated in the `/docs/` folder. + +**⚠️ IMPORTANT FOR AI AGENTS**: Before making any changes, read: +1. **[00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md)** - Versioning, changelog, and DRY principles +2. **[CHANGELOG.md](CHANGELOG.md)** - Current version and change history ### Core Documentation -- **`docs/README.md`** - Documentation index and navigation -- **`docs/01-ARCHITECTURE-TECH-STACK.md`** - Technology stack and system architecture -- **`docs/02-APP-ARCHITECTURE.md`** - Application architecture with complete workflows -- **`docs/03-FRONTEND.md`** - Complete frontend documentation -- **`docs/04-BACKEND.md`** - Complete backend documentation -- **`docs/05-AI-FUNCTIONS.md`** - Complete AI functions documentation -- **`docs/06-CHANGELOG.md`** - System changelog -**Quick Start**: Read `docs/README.md` for navigation, then start with `docs/01-ARCHITECTURE-TECH-STACK.md` for system overview. +0. **[00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md)** ⚠️ **READ FIRST** + - Documentation and changelog management system + - Versioning system (Semantic Versioning) + - Changelog update rules (only after user confirmation) + - DRY principles and standards + - AI agent instructions + +1. **[01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md)** + - Technology stack overview + - Infrastructure components + - Docker deployment architecture + - Fresh installation guide + - External service integrations + +2. **[02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md)** + - IGNY8 application architecture + - System hierarchy and relationships + - User roles and access control + - Module organization + - Complete workflows + - Data models and relationships + - Multi-tenancy architecture + - API architecture + - Security architecture + +3. **[03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md)** + - Frontend architecture + - Project structure + - Routing system + - Template system + - Component library + - State management + - API integration + - Configuration system + - All pages and features + +4. **[04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md)** + - Backend architecture + - Project structure + - Models and relationships + - ViewSets and API endpoints + - Serializers + - Celery tasks + - Middleware + - All modules (Planner, Writer, System, Billing, Auth) + +5. **[05-AI-FRAMEWORK-IMPLEMENTATION.md](docs/05-AI-FRAMEWORK-IMPLEMENTATION.md)** + - AI framework architecture and code structure + - All 5 AI functions (technical implementation) + - AI function execution flow + - Progress tracking + - Cost tracking + - Prompt management + - Model configuration + +6. **[06-FUNCTIONAL-BUSINESS-LOGIC.md](docs/06-FUNCTIONAL-BUSINESS-LOGIC.md)** + - Complete functional and business logic documentation + - All workflows and processes + - All features and functions + - How the application works from business perspective + - Credit system details + - WordPress integration + - Data flow and state management + +### Quick Start Guide + +**For AI Agents**: Start with [00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md) to understand versioning, changelog, and DRY principles. + +1. **New to IGNY8?** Start with [01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md) for technology overview +2. **Understanding the System?** Read [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md) for complete architecture +3. **Frontend Development?** See [03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md) for all frontend details +4. **Backend Development?** See [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) for all backend details +5. **Working with AI?** See [05-AI-FRAMEWORK-IMPLEMENTATION.md](docs/05-AI-FRAMEWORK-IMPLEMENTATION.md) for AI framework implementation +6. **Understanding Business Logic?** See [06-FUNCTIONAL-BUSINESS-LOGIC.md](docs/06-FUNCTIONAL-BUSINESS-LOGIC.md) for complete workflows and features +7. **What's New?** Check [CHANGELOG.md](CHANGELOG.md) for recent changes + +### Finding Information + +**By Topic:** +- **Infrastructure & Deployment**: [01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md) +- **Application Architecture**: [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md) +- **Frontend Development**: [03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md) +- **Backend Development**: [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) +- **AI Framework Implementation**: [05-AI-FRAMEWORK-IMPLEMENTATION.md](docs/05-AI-FRAMEWORK-IMPLEMENTATION.md) +- **Business Logic & Workflows**: [06-FUNCTIONAL-BUSINESS-LOGIC.md](docs/06-FUNCTIONAL-BUSINESS-LOGIC.md) +- **Changes & Updates**: [CHANGELOG.md](CHANGELOG.md) +- **Documentation Management**: [00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md) ⚠️ **For AI Agents** + +**By Module:** +- **Planner**: See [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md) (Module Organization) and [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) (Planner Module) +- **Writer**: See [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md) (Module Organization) and [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) (Writer Module) +- **Thinker**: See [03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md) (Thinker Pages) and [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) (System Module) +- **System**: See [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) (System Module) +- **Billing**: See [04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) (Billing Module) + +--- ## 🛠️ Development -### Backend +### Technology Stack + +**Backend:** - Django 5.2+ - Django REST Framework -- PostgreSQL +- PostgreSQL 15 +- Celery 5.3+ +- Redis 7 -### Frontend +**Frontend:** - React 19 -- TypeScript -- Vite -- Tailwind CSS +- TypeScript 5.7+ +- Vite 6.1+ +- Tailwind CSS 4.0+ +- Zustand 5.0+ + +**Infrastructure:** +- Docker & Docker Compose +- Caddy (Reverse Proxy) +- Portainer (Container Management) + +### System Capabilities + +- **Multi-Tenancy**: Complete account isolation with automatic filtering +- **Planner Module**: Keywords, Clusters, Content Ideas management +- **Writer Module**: Tasks, Content, Images generation and management +- **Thinker Module**: Prompts, Author Profiles, Strategies, Image Testing +- **System Module**: Settings, Integrations, AI Prompts +- **Billing Module**: Credits, Transactions, Usage Logs +- **AI Functions**: 5 AI operations (Auto Cluster, Generate Ideas, Generate Content, Generate Image Prompts, Generate Images) + +--- + +--- + +## 🔒 Documentation & Changelog Management + +### Versioning System + +- **Format**: Semantic Versioning (MAJOR.MINOR.PATCH) +- **Current Version**: `1.0.0` +- **Location**: `CHANGELOG.md` (root directory) +- **Rules**: Only updated after user confirmation that fix/feature is complete + +### Changelog Management + +- **Location**: `CHANGELOG.md` (root directory) +- **Rules**: Only updated after user confirmation +- **Structure**: Added, Changed, Fixed, Deprecated, Removed, Security +- **For Details**: See [00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md) + +### DRY Principles + +**Core Principle**: Always use existing, predefined, standardized components, utilities, functions, and configurations. + +**Frontend**: Use existing templates, components, stores, contexts, utilities, and Tailwind CSS +**Backend**: Use existing base classes, AI framework, services, and middleware + +**For Complete Guidelines**: See [00-DOCUMENTATION-MANAGEMENT.md](docs/00-DOCUMENTATION-MANAGEMENT.md) + +**⚠️ For AI Agents**: Read `docs/00-DOCUMENTATION-MANAGEMENT.md` at the start of every session. + +--- ## 📝 License [Add license information] +--- + +## 📞 Support + +For questions or clarifications about the documentation, refer to the specific document in the `/docs/` folder or contact the development team. diff --git a/docs/00-DOCUMENTATION-MANAGEMENT.md b/docs/00-DOCUMENTATION-MANAGEMENT.md new file mode 100644 index 00000000..ace6cf11 --- /dev/null +++ b/docs/00-DOCUMENTATION-MANAGEMENT.md @@ -0,0 +1,397 @@ +# 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 + +``` +docs/ +├── 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 +``` + +### 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 +**Version:** 1.0.0 +**Status:** Locked + diff --git a/docs/01-ARCHITECTURE-TECH-STACK.md b/docs/01-ARCHITECTURE-TECH-STACK.md deleted file mode 100644 index 8f2df388..00000000 --- a/docs/01-ARCHITECTURE-TECH-STACK.md +++ /dev/null @@ -1,476 +0,0 @@ -# IGNY8 Architecture & Technology Stack - -**Last Updated:** 2025-01-XX -**Purpose:** Complete technology stack and architecture overview for the IGNY8 platform. - ---- - -## Table of Contents - -1. [Executive Summary](#executive-summary) -2. [Technology Stack](#technology-stack) -3. [System Architecture](#system-architecture) -4. [Core Architecture Principles](#core-architecture-principles) -5. [Infrastructure Components](#infrastructure-components) -6. [External Service Integrations](#external-service-integrations) -7. [Deployment Architecture](#deployment-architecture) - ---- - -## Executive Summary - -**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system is built with modern technologies and follows a multi-tenant architecture with complete account isolation. - -### Key Metrics - -- **Architecture**: Multi-tenant SaaS with account isolation -- **Backend**: Django 5.2+ with Django REST Framework -- **Frontend**: React 19 with TypeScript -- **Database**: PostgreSQL 15 -- **Task Queue**: Celery with Redis -- **Deployment**: Docker-based containerization -- **Reverse Proxy**: Caddy (HTTPS termination) -- **AI Functions**: 5 primary AI operations -- **Modules**: 4 core modules (Planner, Writer, System, Billing) - ---- - -## Technology Stack - -### Backend Stack - -| Component | Technology | Version | Purpose | -|-----------|------------|---------|---------| -| **Framework** | Django | 5.2+ | Web framework | -| **API Framework** | Django REST Framework | Latest | RESTful API | -| **Database** | PostgreSQL | 15 | Primary database | -| **Task Queue** | Celery | Latest | Asynchronous tasks | -| **Cache/Broker** | Redis | 7 | Celery broker & caching | -| **Authentication** | JWT | SimpleJWT | Token-based auth | -| **HTTP Client** | Requests | Latest | External API calls | -| **WSGI Server** | Gunicorn | Latest | Production server | - -### Frontend Stack - -| Component | Technology | Version | Purpose | -|-----------|------------|---------|---------| -| **Framework** | React | 19 | UI library | -| **Language** | TypeScript | Latest | Type safety | -| **Build Tool** | Vite | Latest | Build tool & dev server | -| **Styling** | Tailwind CSS | Latest | Utility-first CSS | -| **State Management** | Zustand | Latest | Lightweight state | -| **Routing** | React Router | v6 | Client-side routing | -| **HTTP Client** | Fetch API | Native | API communication | - -### Infrastructure Stack - -| Component | Technology | Purpose | -|-----------|------------|---------| -| **Containerization** | Docker | Application containers | -| **Orchestration** | Docker Compose | Multi-container orchestration | -| **Reverse Proxy** | Caddy | HTTPS termination & routing | -| **Database Admin** | pgAdmin | PostgreSQL administration | -| **File Management** | FileBrowser | Web-based file management | -| **Container Management** | Portainer | Docker container management | - -### External Services - -| Service | Purpose | Integration | -|---------|---------|-------------| -| **OpenAI API** | Text generation (GPT models) | API integration | -| **OpenAI DALL-E** | Image generation | API integration | -| **Runware API** | Alternative image generation | API integration | -| **WordPress** | Content publishing | REST API integration | -| **Stripe** | Payment processing | Webhook integration (planned) | - ---- - -## System Architecture - -### High-Level Architecture - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Client Layer │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Browser │ │ Mobile │ │ Admin │ │ -│ │ (React) │ │ (Future) │ │ Panel │ │ -│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ -└─────────┼──────────────────┼──────────────────┼─────────────┘ - │ │ │ - └──────────────────┼──────────────────┘ - │ -┌────────────────────────────┼──────────────────────────────┐ -│ Reverse Proxy Layer │ -│ ┌───────────────┐ │ -│ │ Caddy │ │ -│ │ (HTTPS/443) │ │ -│ └───────┬───────┘ │ -└────────────────────────────┼──────────────────────────────┘ - │ -┌────────────────────────────┼──────────────────────────────┐ -│ Application Layer │ -│ ┌──────────────┐ ┌──────────────┐ │ -│ │ Frontend │ │ Backend │ │ -│ │ (React) │◄─────────────┤ (Django) │ │ -│ │ Port 8021 │ REST API │ Port 8011 │ │ -│ └──────────────┘ └──────┬───────┘ │ -│ │ │ -│ ┌────────┴────────┐ │ -│ │ Celery Worker │ │ -│ │ (Async Tasks) │ │ -│ └────────┬────────┘ │ -└───────────────────────────────────────┼──────────────────┘ - │ -┌───────────────────────────────────────┼──────────────────┐ -│ Data Layer │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ PostgreSQL │ │ Redis │ │ Storage │ │ -│ │ (Database) │ │ (Cache/Broker)│ │ (Files) │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -└──────────────────────────────────────────────────────────┘ - │ -┌───────────────────────────────────────┼──────────────────┐ -│ External Services │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ OpenAI │ │ Runware │ │ WordPress │ │ -│ │ (GPT/DALL-E)│ │ (Images) │ │ (Publish) │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -└──────────────────────────────────────────────────────────┘ -``` - -### Request Flow - -``` -1. User Request - ↓ -2. Browser (React Frontend) - ↓ -3. Caddy Reverse Proxy (HTTPS Termination) - ↓ -4. Django Backend (API Endpoint) - ↓ -5. AccountContextMiddleware (Account Isolation) - ↓ -6. ViewSet (Business Logic) - ↓ -7. Serializer (Validation) - ↓ -8. Model (Database) - ↓ -9. Response (JSON) - ↓ -10. Frontend (UI Update) -``` - -### AI Task Flow - -``` -1. User Action (e.g., "Auto Cluster Keywords") - ↓ -2. Frontend API Call - ↓ -3. Backend Endpoint (ViewSet Action) - ↓ -4. Celery Task Queued - ↓ -5. Task ID Returned to Frontend - ↓ -6. Frontend Polls Progress Endpoint - ↓ -7. Celery Worker Processes Task - ↓ -8. AIProcessor Makes API Calls - ↓ -9. Results Saved to Database - ↓ -10. Progress Updates Sent - ↓ -11. Frontend Displays Results -``` - ---- - -## Core Architecture Principles - -### 1. Configuration-Driven Everything - -**Principle**: Zero HTML/JSX duplication - All UI rendered from configuration. - -**Implementation**: -- **Frontend**: Config files in `/config/pages/` and `/config/snippets/` -- **Backend**: DRF serializers and ViewSet actions -- **Templates**: 4 universal templates (Dashboard, Table, Form, System) - -**Benefits**: -- Single source of truth -- Easy maintenance -- Consistent UI/UX -- Rapid feature development - -### 2. Multi-Tenancy Foundation - -**Principle**: Complete account isolation with automatic filtering. - -**Implementation**: -- All models inherit `AccountBaseModel` -- All ViewSets inherit `AccountModelViewSet` -- Middleware injects account context from JWT -- Site > Sector hierarchy for content organization - -**Benefits**: -- Data security -- Scalability -- Resource isolation -- Simplified access control - -### 3. Template System (4 Universal Templates) - -**Principle**: Reusable templates for all page types. - -| Template | Purpose | Usage | -|----------|---------|-------| -| **DashboardTemplate** | Module home pages | KPIs, workflow steps, charts | -| **TablePageTemplate** | CRUD table pages | Keywords, Clusters, Tasks, etc. | -| **FormPageTemplate** | Settings/form pages | Settings, Integration, etc. | -| **SystemPageTemplate** | System/admin pages | Logs, Status, Monitoring | - -### 4. Unified AI Processor - -**Principle**: Single interface for all AI operations. - -**Implementation**: -- Single `AIEngine` class orchestrates all AI operations -- All AI functions inherit from `BaseAIFunction` -- Manual and automated workflows use same functions -- Account-specific API keys and model configuration - -**Benefits**: -- Code reusability -- Consistent error handling -- Unified logging -- Easy to extend - -### 5. Module-Based Organization - -**Principle**: Clear module boundaries with shared utilities. - -**Modules**: -- **Planner**: Keywords, Clusters, Ideas -- **Writer**: Tasks, Content, Images -- **System**: Settings, Prompts, Integration -- **Billing**: Credits, Transactions, Usage -- **Auth**: Accounts, Users, Sites, Sectors - ---- - -## Infrastructure Components - -### Docker Architecture - -The system uses a two-stack Docker architecture: - -1. **Infrastructure Stack (`igny8-infra`)**: Shared services -2. **Application Stack (`igny8-app`)**: Application-specific services - -### Infrastructure Stack Services - -| Service | Container Name | Port | Purpose | -|---------|----------------|------|---------| -| **PostgreSQL** | `igny8_postgres` | 5432 (internal) | Database | -| **Redis** | `igny8_redis` | 6379 (internal) | Cache & Celery broker | -| **pgAdmin** | `igny8_pgadmin` | 5050:80 | Database administration | -| **FileBrowser** | `igny8_filebrowser` | 8080:80 | File management | -| **Caddy** | `igny8_caddy` | 80:80, 443:443 | Reverse proxy & HTTPS | -| **Setup Helper** | `setup-helper` | - | Utility container | - -### Application Stack Services - -| Service | Container Name | Port | Purpose | -|---------|----------------|------|---------| -| **Backend** | `igny8_backend` | 8011:8010 | Django REST API | -| **Frontend** | `igny8_frontend` | 8021:5173 | React application | -| **Celery Worker** | `igny8_celery_worker` | - | Async task processing | -| **Celery Beat** | `igny8_celery_beat` | - | Scheduled tasks | - -### Network Configuration - -- **Network Name**: `igny8_net` -- **Type**: External bridge network -- **Purpose**: Inter-container communication -- **Creation**: Must be created manually before starting stacks - -### Volume Management - -**Infrastructure Volumes**: -- `pgdata`: PostgreSQL database data -- `redisdata`: Redis data -- `pgadmin_data`: pgAdmin configuration -- `filebrowser_db`: FileBrowser database -- `caddy_data`: Caddy SSL certificates -- `caddy_config`: Caddy configuration - -**Application Volumes**: -- Host mounts for application code -- Host mounts for logs -- Docker socket for container management - -### Port Allocation - -| Service | External Port | Internal Port | Access | -|---------|---------------|---------------|--------| -| **pgAdmin** | 5050 | 80 | http://localhost:5050 | -| **FileBrowser** | 8080 | 80 | http://localhost:8080 | -| **Caddy** | 80, 443 | 80, 443 | https://domain.com | -| **Backend** | 8011 | 8010 | http://localhost:8011 | -| **Frontend** | 8021 | 5173 | http://localhost:8021 | - ---- - -## External Service Integrations - -### OpenAI Integration - -**Purpose**: Text generation and image generation - -**Services Used**: -- GPT models for text generation -- DALL-E for image generation - -**Configuration**: -- API key stored per account in `IntegrationSettings` -- Model selection per account -- Cost tracking per request - -### 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 - ---- - -## Deployment Architecture - -### Deployment Model - -**Container-Based**: All services run in Docker containers - -**Stack Separation**: -- Infrastructure stack runs independently -- Application stack depends on infrastructure stack -- Both stacks share the same Docker network - -### Environment Configuration - -**Backend Environment Variables**: -- Database connection (PostgreSQL) -- Redis connection -- Django settings (DEBUG, SECRET_KEY, etc.) -- JWT settings -- Celery configuration - -**Frontend Environment Variables**: -- Backend API URL -- Environment (development/production) - -**Infrastructure Environment Variables**: -- PostgreSQL credentials -- pgAdmin credentials -- FileBrowser configuration - -### Health Checks - -**Backend Health Check**: -- Endpoint: `/api/v1/system/status/` -- Interval: 30 seconds -- Timeout: 10 seconds -- Retries: 3 - -**PostgreSQL Health Check**: -- Command: `pg_isready` -- Interval: 20 seconds -- Timeout: 3 seconds -- Retries: 5 - -**Redis Health Check**: -- Command: `redis-cli ping` -- Interval: 20 seconds -- Timeout: 3 seconds -- Retries: 5 - -### Scaling Considerations - -**Horizontal Scaling**: -- Multiple Celery workers can be added -- Multiple backend instances can be added (with load balancer) -- Frontend can be scaled independently - -**Vertical Scaling**: -- Database can be scaled with more resources -- Redis can be scaled with more memory -- Containers can be allocated more CPU/memory - -### Backup & Recovery - -**Database Backups**: -- PostgreSQL dumps stored in `/data/backups` -- Automated backup scripts -- Point-in-time recovery support - -**Volume Backups**: -- Docker volume backups -- Application code backups -- Configuration backups - ---- - -## Summary - -The IGNY8 platform is built on a modern, scalable architecture using: - -- **Django 5.2+** for the backend API -- **React 19** for the frontend -- **PostgreSQL 15** for data storage -- **Celery & Redis** for async processing -- **Docker** for containerization -- **Caddy** for reverse proxy and HTTPS - -The architecture follows principles of: -- Configuration-driven development -- Multi-tenancy with account isolation -- Module-based organization -- Unified AI processing -- Template-based UI rendering - -This architecture supports scalability, maintainability, and rapid feature development while ensuring data security and isolation. - diff --git a/docs/01-TECH-STACK-AND-INFRASTRUCTURE.md b/docs/01-TECH-STACK-AND-INFRASTRUCTURE.md new file mode 100644 index 00000000..ec355ba6 --- /dev/null +++ b/docs/01-TECH-STACK-AND-INFRASTRUCTURE.md @@ -0,0 +1,1153 @@ +# IGNY8 Technology Stack & Infrastructure + +**Last Updated:** 2025-01-XX +**Purpose:** Complete technology stack, infrastructure setup, Docker deployment, and fresh installation guide for the IGNY8 platform. + +--- + +## Table of Contents + +1. [Executive Summary](#executive-summary) +2. [Technology Stack](#technology-stack) +3. [System Architecture](#system-architecture) +4. [Core Architecture Principles](#core-architecture-principles) +5. [Infrastructure Components](#infrastructure-components) +6. [External Service Integrations](#external-service-integrations) +7. [Deployment Architecture](#deployment-architecture) +8. [Complete Fresh Installation Guide](#complete-fresh-installation-guide) + +--- + +## Executive Summary + +**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system is built with modern technologies and follows a multi-tenant architecture with complete account isolation. + +### Key Metrics + +- **Architecture**: Multi-tenant SaaS with account isolation +- **Backend**: Django 5.2+ with Django REST Framework +- **Frontend**: React 19 with TypeScript +- **Database**: PostgreSQL 15 +- **Task Queue**: Celery with Redis +- **Deployment**: Docker-based containerization +- **Reverse Proxy**: Caddy (HTTPS termination) +- **AI Functions**: 5 primary AI operations +- **Modules**: 5 core modules (Planner, Writer, Thinker, System, Billing) + +--- + +## Technology Stack + +### Backend Stack + +| Component | Technology | Version | Purpose | +|-----------|------------|---------|---------| +| **Framework** | Django | 5.2.7+ | Web framework | +| **API Framework** | Django REST Framework | Latest | RESTful API | +| **Database** | PostgreSQL | 15 | Primary database | +| **Database Adapter** | psycopg2-binary | Latest | PostgreSQL Python adapter | +| **Task Queue** | Celery | 5.3.0+ | Asynchronous tasks | +| **Cache/Broker** | Redis | 7 | Celery broker & caching | +| **Authentication** | JWT | PyJWT 2.8.0+ | Token-based auth | +| **HTTP Client** | Requests | 2.31.0+ | External API calls | +| **WSGI Server** | Gunicorn | Latest | Production server | +| **Static Files** | WhiteNoise | Latest | Static file serving | +| **HTML Parsing** | BeautifulSoup4 | 4.12.0+ | HTML parsing & processing | +| **System Utils** | psutil | 5.9.0+ | System & process utilities | +| **Docker Client** | docker | 7.0.0+ | Docker API client | +| **Django Packages** | django-filter | Latest | Advanced filtering | +| **Django Packages** | django-cors-headers | Latest | CORS handling | + +### Frontend Stack + +| Component | Technology | Version | Purpose | +|-----------|------------|---------|---------| +| **Framework** | React | 19.0.0 | UI library | +| **Framework** | React DOM | 19.0.0 | DOM rendering | +| **Language** | TypeScript | 5.7.2 | Type safety | +| **Build Tool** | Vite | 6.1.0 | Build tool & dev server | +| **Styling** | Tailwind CSS | 4.0.8 | Utility-first CSS | +| **State Management** | Zustand | 5.0.8 | Lightweight state | +| **Routing** | React Router | v7.9.5 | Client-side routing | +| **HTTP Client** | Fetch API | Native | API communication | +| **SEO** | react-helmet-async | 2.0.5 | Dynamic head management | + +### Frontend UI Libraries + +| Library | Version | Purpose | +|---------|---------|---------| +| **Icons** | @heroicons/react | 2.2.0 | Icon library | +| **Charts** | apexcharts | 4.1.0 | Chart library | +| **Charts** | react-apexcharts | 1.7.0 | React wrapper for ApexCharts | +| **Calendar** | @fullcalendar/core | 6.1.15 | Calendar component | +| **Calendar** | @fullcalendar/react | 6.1.15 | React wrapper for FullCalendar | +| **Calendar** | @fullcalendar/daygrid | 6.1.15 | Day grid view | +| **Calendar** | @fullcalendar/timegrid | 6.1.15 | Time grid view | +| **Calendar** | @fullcalendar/interaction | 6.1.15 | Calendar interactions | +| **Calendar** | @fullcalendar/list | 6.1.15 | List view | +| **Maps** | @react-jvectormap/core | 1.0.4 | Vector map library | +| **Maps** | @react-jvectormap/world | 1.1.2 | World map component | +| **Carousel** | swiper | 11.2.3 | Carousel/slider component | +| **Date Picker** | flatpickr | 4.6.13 | Date/time picker | +| **Drag & Drop** | react-dnd | 16.0.1 | Drag and drop functionality | +| **Drag & Drop** | react-dnd-html5-backend | 16.0.1 | HTML5 drag & drop backend | +| **File Upload** | react-dropzone | 14.3.5 | File upload component | + +### Frontend Utilities + +| Library | Version | Purpose | +|---------|---------|---------| +| **Class Utils** | clsx | 2.1.1 | Conditional class names | +| **Tailwind Utils** | tailwind-merge | 3.0.1 | Merge Tailwind classes | + +### Frontend Development Tools + +| Tool | Version | Purpose | +|------|---------|---------| +| **Linter** | ESLint | 9.19.0 | Code linting | +| **TypeScript Linter** | typescript-eslint | 8.22.0 | TypeScript linting | +| **Vite Plugin** | @vitejs/plugin-react | 4.3.4 | React plugin for Vite | +| **SVG Plugin** | vite-plugin-svgr | 4.3.0 | SVG as React components | +| **PostCSS** | postcss | 8.5.2 | CSS processing | +| **Tailwind PostCSS** | @tailwindcss/postcss | 4.0.8 | Tailwind PostCSS plugin | + +### Infrastructure Stack + +| Component | Technology | Purpose | +|-----------|------------|---------| +| **Containerization** | Docker | Application containers | +| **Orchestration** | Docker Compose | Multi-container orchestration | +| **Reverse Proxy** | Caddy | HTTPS termination & routing | +| **Database Admin** | pgAdmin | PostgreSQL administration | +| **File Management** | FileBrowser | Web-based file management | +| **Container Management** | Portainer | Docker container management | + +### External Services + +| Service | Purpose | Integration | +|---------|---------|-------------| +| **OpenAI API** | Text generation (GPT models) | API integration | +| **OpenAI DALL-E** | Image generation | API integration | +| **Runware API** | Alternative image generation | API integration | +| **WordPress** | Content publishing | REST API integration | +| **Stripe** | Payment processing | Webhook integration (planned) | + +--- + +## System Architecture + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Client Layer │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Browser │ │ Mobile │ │ Admin │ │ +│ │ (React) │ │ (Future) │ │ Panel │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ +└─────────┼──────────────────┼──────────────────┼─────────────┘ + │ │ │ + └──────────────────┼──────────────────┘ + │ +┌────────────────────────────┼──────────────────────────────┐ +│ Reverse Proxy Layer │ +│ ┌───────────────┐ │ +│ │ Caddy │ │ +│ │ (HTTPS/443) │ │ +│ └───────┬───────┘ │ +└────────────────────────────┼──────────────────────────────┘ + │ +┌────────────────────────────┼──────────────────────────────┐ +│ Application Layer │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Frontend │ │ Backend │ │ +│ │ (React) │◄─────────────┤ (Django) │ │ +│ │ Port 8021 │ REST API │ Port 8011 │ │ +│ └──────────────┘ └──────┬───────┘ │ +│ │ │ +│ ┌────────┴────────┐ │ +│ │ Celery Worker │ │ +│ │ (Async Tasks) │ │ +│ └────────┬────────┘ │ +└───────────────────────────────────────┼──────────────────┘ + │ +┌───────────────────────────────────────┼──────────────────┐ +│ Data Layer │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ PostgreSQL │ │ Redis │ │ Storage │ │ +│ │ (Database) │ │ (Cache/Broker)│ │ (Files) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└──────────────────────────────────────────────────────────┘ + │ +┌───────────────────────────────────────┼──────────────────┐ +│ External Services │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ OpenAI │ │ Runware │ │ WordPress │ │ +│ │ (GPT/DALL-E)│ │ (Images) │ │ (Publish) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└──────────────────────────────────────────────────────────┘ +``` + +### Request Flow + +``` +1. User Request + ↓ +2. Browser (React Frontend) + ↓ +3. Caddy Reverse Proxy (HTTPS Termination) + ↓ +4. Django Backend (API Endpoint) + ↓ +5. AccountContextMiddleware (Account Isolation) + ↓ +6. ViewSet (Business Logic) + ↓ +7. Serializer (Validation) + ↓ +8. Model (Database) + ↓ +9. Response (JSON) + ↓ +10. Frontend (UI Update) +``` + +### AI Task Flow + +``` +1. User Action (e.g., "Auto Cluster Keywords") + ↓ +2. Frontend API Call + ↓ +3. Backend Endpoint (ViewSet Action) + ↓ +4. Celery Task Queued + ↓ +5. Task ID Returned to Frontend + ↓ +6. Frontend Polls Progress Endpoint + ↓ +7. Celery Worker Processes Task + ↓ +8. AIProcessor Makes API Calls + ↓ +9. Results Saved to Database + ↓ +10. Progress Updates Sent + ↓ +11. Frontend Displays Results +``` + +--- + +## Core Architecture Principles + +### 1. Configuration-Driven Everything + +**Principle**: Zero HTML/JSX duplication - All UI rendered from configuration. + +**Implementation**: +- **Frontend**: Config files in `/config/pages/` and `/config/snippets/` +- **Backend**: DRF serializers and ViewSet actions +- **Templates**: 4 universal templates (Dashboard, Table, Form, System) + +**Benefits**: +- Single source of truth +- Easy maintenance +- Consistent UI/UX +- Rapid feature development + +### 2. Multi-Tenancy Foundation + +**Principle**: Complete account isolation with automatic filtering. + +**Implementation**: +- All models inherit `AccountBaseModel` +- All ViewSets inherit `AccountModelViewSet` +- Middleware injects account context from JWT +- Site > Sector hierarchy for content organization + +**Benefits**: +- Data security +- Scalability +- Resource isolation +- Simplified access control + +### 3. Template System (4 Universal Templates) + +**Principle**: Reusable templates for all page types. + +| Template | Purpose | Usage | +|----------|---------|-------| +| **DashboardTemplate** | Module home pages | KPIs, workflow steps, charts | +| **TablePageTemplate** | CRUD table pages | Keywords, Clusters, Tasks, etc. | +| **FormPageTemplate** | Settings/form pages | Settings, Integration, etc. | +| **SystemPageTemplate** | System/admin pages | Logs, Status, Monitoring | + +### 4. Unified AI Processor + +**Principle**: Single interface for all AI operations. + +**Implementation**: +- Single `AIEngine` class orchestrates all AI operations +- All AI functions inherit from `BaseAIFunction` +- Manual and automated workflows use same functions +- Account-specific API keys and model configuration + +**Benefits**: +- Code reusability +- Consistent error handling +- Unified logging +- Easy to extend + +### 5. Module-Based Organization + +**Principle**: Clear module boundaries with shared utilities. + +**Modules**: +- **Planner**: Keywords, Clusters, Ideas +- **Writer**: Tasks, Content, Images +- **Thinker**: Prompts, Author Profiles, Strategies, Image Testing +- **System**: Settings, Integrations, AI Configuration +- **Billing**: Credits, Transactions, Usage +- **Auth**: Accounts, Users, Sites, Sectors + +--- + +## Infrastructure Components + +### Docker Architecture + +The system uses a two-stack Docker architecture: + +1. **Infrastructure Stack (`igny8-infra`)**: Shared services +2. **Application Stack (`igny8-app`)**: Application-specific services + +### Infrastructure Stack Services + +| Service | Container Name | Port | Purpose | +|---------|----------------|------|---------| +| **PostgreSQL** | `igny8_postgres` | 5432 (internal) | Database | +| **Redis** | `igny8_redis` | 6379 (internal) | Cache & Celery broker | +| **pgAdmin** | `igny8_pgadmin` | 5050:80 | Database administration | +| **FileBrowser** | `igny8_filebrowser` | 8080:80 | File management | +| **Caddy** | `igny8_caddy` | 80:80, 443:443 | Reverse proxy & HTTPS | +| **Setup Helper** | `setup-helper` | - | Utility container | + +### Application Stack Services + +| Service | Container Name | Port | Purpose | +|---------|----------------|------|---------| +| **Backend** | `igny8_backend` | 8011:8010 | Django REST API | +| **Frontend** | `igny8_frontend` | 8021:5173 | React application (main app) | +| **Marketing Dev** | `igny8_marketing_dev` | 8023:5174 | Marketing site (dev server) | +| **Celery Worker** | `igny8_celery_worker` | - | Async task processing | +| **Celery Beat** | `igny8_celery_beat` | - | Scheduled tasks | + +### Network Configuration + +- **Network Name**: `igny8_net` +- **Type**: External bridge network +- **Purpose**: Inter-container communication +- **Creation**: Must be created manually before starting stacks + +### Volume Management + +**Infrastructure Volumes**: +- `pgdata`: PostgreSQL database data +- `redisdata`: Redis data +- `pgadmin_data`: pgAdmin configuration +- `filebrowser_db`: FileBrowser database +- `caddy_data`: Caddy SSL certificates +- `caddy_config`: Caddy configuration + +**Application Volumes**: +- Host mounts for application code +- Host mounts for logs +- Docker socket for container management + +### Port Allocation + +| Service | External Port | Internal Port | Access | +|---------|---------------|---------------|--------| +| **pgAdmin** | 5050 | 80 | http://localhost:5050 | +| **FileBrowser** | 8080 | 80 | http://localhost:8080 | +| **Caddy** | 80, 443 | 80, 443 | https://domain.com | +| **Backend** | 8011 | 8010 | http://localhost:8011 | +| **Frontend** | 8021 | 5173 | http://localhost:8021 | +| **Marketing Dev** | 8023 | 5174 | http://localhost:8023 | + +--- + +## External Service Integrations + +### OpenAI Integration + +**Purpose**: Text generation and image generation + +**Services Used**: +- GPT models for text generation +- DALL-E for image generation + +**Configuration**: +- API key stored per account in `IntegrationSettings` +- Model selection per account +- Cost tracking per request + +### 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 + +--- + +## Deployment Architecture + +### Deployment Model + +**Container-Based**: All services run in Docker containers + +**Stack Separation**: +- Infrastructure stack runs independently +- Application stack depends on infrastructure stack +- Both stacks share the same Docker network + +### Environment Configuration + +**Backend Environment Variables**: +- Database connection (PostgreSQL) +- Redis connection +- Django settings (DEBUG, SECRET_KEY, etc.) +- JWT settings +- Celery configuration + +**Frontend Environment Variables**: +- Backend API URL +- Environment (development/production) + +**Infrastructure Environment Variables**: +- PostgreSQL credentials +- pgAdmin credentials +- FileBrowser configuration + +### Health Checks + +**Backend Health Check**: +- Endpoint: `/api/v1/system/status/` +- Interval: 30 seconds +- Timeout: 10 seconds +- Retries: 3 + +**PostgreSQL Health Check**: +- Command: `pg_isready` +- Interval: 20 seconds +- Timeout: 3 seconds +- Retries: 5 + +**Redis Health Check**: +- Command: `redis-cli ping` +- Interval: 20 seconds +- Timeout: 3 seconds +- Retries: 5 + +### Scaling Considerations + +**Horizontal Scaling**: +- Multiple Celery workers can be added +- Multiple backend instances can be added (with load balancer) +- Frontend can be scaled independently + +**Vertical Scaling**: +- Database can be scaled with more resources +- Redis can be scaled with more memory +- Containers can be allocated more CPU/memory + +### Backup & Recovery + +**Database Backups**: +- PostgreSQL dumps stored in `/data/backups` +- Automated backup scripts +- Point-in-time recovery support + +**Volume Backups**: +- Docker volume backups +- Application code backups +- Configuration backups + +--- + +## Summary + +The IGNY8 platform is built on a modern, scalable architecture using: + +- **Django 5.2+** for the backend API +- **React 19** for the frontend +- **PostgreSQL 15** for data storage +- **Celery & Redis** for async processing +- **Docker** for containerization +- **Caddy** for reverse proxy and HTTPS + +The architecture follows principles of: +- Configuration-driven development +- Multi-tenancy with account isolation +- Module-based organization +- Unified AI processing +- Template-based UI rendering + +This architecture supports scalability, maintainability, and rapid feature development while ensuring data security and isolation. + +--- + +## Complete Fresh Installation Guide + +This guide covers installing IGNY8 on a fresh Ubuntu VPS from scratch, including all prerequisites, Docker, Portainer, and the complete IGNY8 application stack. + +### Prerequisites + +**System Requirements**: +- **OS**: Ubuntu 22.04 LTS or 24.04 LTS (recommended) +- **RAM**: Minimum 4GB (8GB+ recommended for production) +- **CPU**: 2+ cores (4+ cores recommended) +- **Storage**: 50GB+ free space +- **Network**: Static IP address or domain name +- **Access**: Root or sudo access + +**Domain Setup** (Optional but recommended): +- Domain name pointing to server IP +- DNS records configured: + - `igny8.com` → Server IP + - `www.igny8.com` → Server IP + - `app.igny8.com` → Server IP + - `api.igny8.com` → Server IP + +--- + +### Step 1: Initial Server Setup + +#### 1.1 Update System + +```bash +# Update package list +sudo apt update && sudo apt upgrade -y + +# Install essential tools +sudo apt install -y curl wget git vim ufw software-properties-common apt-transport-https ca-certificates gnupg lsb-release +``` + +#### 1.2 Configure Firewall + +```bash +# Enable UFW firewall +sudo ufw enable + +# Allow SSH (adjust port if needed) +sudo ufw allow 22/tcp + +# Allow HTTP and HTTPS +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp + +# Allow Portainer (if accessing directly) +sudo ufw allow 9000/tcp + +# Check firewall status +sudo ufw status +``` + +#### 1.3 Create Application User (Optional but Recommended) + +```bash +# Create user for application +sudo adduser igny8 +sudo usermod -aG sudo igny8 + +# Switch to application user +su - igny8 +``` + +--- + +### Step 2: Install Docker + +#### 2.1 Install Docker Engine + +```bash +# Remove old Docker versions if any +sudo apt remove -y docker docker-engine docker.io containerd runc + +# Add Docker's official GPG key +sudo install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +sudo chmod a+r /etc/apt/keyrings/docker.gpg + +# Set up Docker repository +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +# Install Docker Engine +sudo apt update +sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + +# Verify Docker installation +sudo docker --version +sudo docker compose version +``` + +#### 2.2 Configure Docker (Optional) + +```bash +# Add user to docker group (to run docker without sudo) +sudo usermod -aG docker $USER + +# Apply group changes (logout/login or use newgrp) +newgrp docker + +# Test Docker without sudo +docker run hello-world + +# Configure Docker to start on boot +sudo systemctl enable docker +sudo systemctl start docker +``` + +--- + +### Step 3: Install Portainer + +#### 3.1 Create Portainer Volume + +```bash +# Create volume for Portainer data +docker volume create portainer_data +``` + +#### 3.2 Run Portainer Container + +```bash +# Run Portainer Community Edition +docker run -d \ + -p 9000:9000 \ + --name=portainer \ + --restart=always \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v portainer_data:/data \ + portainer/portainer-ce:latest +``` + +#### 3.3 Access Portainer + +1. Open browser: `http://your-server-ip:9000` +2. Create admin account (first-time setup) +3. Select "Docker" environment +4. Portainer dashboard will load + +**Note**: For production, configure Portainer behind Caddy reverse proxy with HTTPS. + +--- + +### Step 4: Create Docker Network + +```bash +# Create external network for IGNY8 services +docker network create igny8_net + +# Verify network creation +docker network ls | grep igny8_net +``` + +**Important**: This network must exist before starting IGNY8 services. + +--- + +### Step 5: Prepare Application Directories + +#### 5.1 Create Directory Structure + +```bash +# Create main application directory +sudo mkdir -p /data/app +sudo chown $USER:$USER /data/app + +# Create subdirectories +mkdir -p /data/app/igny8 +mkdir -p /data/app/logs +mkdir -p /data/backups +``` + +#### 5.2 Clone or Copy IGNY8 Repository + +**Option A: Git Clone** (if repository is available): +```bash +cd /data/app +git clone igny8 +cd igny8 +``` + +**Option B: Copy Files** (if files are already available): +```bash +# Copy application files to /data/app/igny8 +# Ensure all files are in place: +# - backend/ +# - frontend/ +# - docker-compose.yml (infrastructure) +# - docker-compose.app.yml (application) +``` + +--- + +### Step 6: Install Infrastructure Stack + +#### 6.1 Navigate to Infrastructure Directory + +```bash +cd /data/app +# Infrastructure docker-compose.yml should be here +``` + +#### 6.2 Configure Infrastructure + +**Edit `docker-compose.yml`** (if needed): +- Update PostgreSQL credentials +- Update pgAdmin credentials +- Configure Caddy domain names +- Set volume paths + +#### 6.3 Start Infrastructure Stack + +```bash +# Start infrastructure services +docker compose -f docker-compose.yml -p igny8-infra up -d + +# Verify services are running +docker compose -f docker-compose.yml -p igny8-infra ps + +# Check logs +docker compose -f docker-compose.yml -p igny8-infra logs -f +``` + +**Infrastructure Services**: +- PostgreSQL (database) +- Redis (cache/broker) +- pgAdmin (database admin) +- FileBrowser (file management) +- Caddy (reverse proxy) + +#### 6.4 Verify Infrastructure + +```bash +# Check PostgreSQL +docker exec igny8_postgres pg_isready + +# Check Redis +docker exec igny8_redis redis-cli ping + +# Check all containers +docker ps | grep igny8 +``` + +--- + +### Step 7: Build Application Images + +#### 7.1 Build Backend Image + +```bash +cd /data/app/igny8/backend + +# Build backend Docker image +docker build -t igny8-backend:latest -f Dockerfile . + +# Verify image +docker images | grep igny8-backend +``` + +#### 7.2 Build Frontend Images + +```bash +cd /data/app/igny8/frontend + +# Build main app dev image +docker build -t igny8-frontend-dev:latest -f Dockerfile.dev . + +# Build marketing dev image +docker build -t igny8-marketing-dev:latest -f Dockerfile.marketing.dev . + +# Verify images +docker images | grep igny8-frontend +docker images | grep igny8-marketing +``` + +**Note**: For production, also build production images: +```bash +# Production frontend image +docker build -t igny8-frontend:latest -f Dockerfile . + +# Production marketing image +docker build -t igny8-marketing:latest -f Dockerfile.marketing . +``` + +--- + +### Step 8: Configure Application + +#### 8.1 Configure Environment Variables + +**Backend Environment** (in `docker-compose.app.yml` or `.env`): +```bash +# Database +DB_HOST=postgres +DB_NAME=igny8_db +DB_USER=igny8 +DB_PASSWORD=your_secure_password + +# Redis +REDIS_HOST=redis +REDIS_PORT=6379 + +# Django +SECRET_KEY=your_django_secret_key +DEBUG=False +USE_SECURE_COOKIES=True +USE_SECURE_PROXY_HEADER=True + +# JWT Settings (if needed) +JWT_SECRET_KEY=your_jwt_secret_key +``` + +**Frontend Environment**: +```bash +# In docker-compose.app.yml +VITE_BACKEND_URL=https://api.igny8.com/api +``` + +#### 8.2 Configure Caddy + +**Edit Caddyfile** for domain routing: +- `igny8.com` → Marketing site +- `app.igny8.com` → Main application +- `api.igny8.com` → Backend API + +--- + +### Step 9: Start Application Stack + +#### 9.1 Navigate to Application Directory + +```bash +cd /data/app/igny8 +``` + +#### 9.2 Start Application Services + +```bash +# Start application stack +docker compose -f docker-compose.app.yml -p igny8-app up -d + +# Verify services +docker compose -f docker-compose.app.yml -p igny8-app ps + +# Check logs +docker compose -f docker-compose.app.yml -p igny8-app logs -f +``` + +#### 9.3 Verify All Services + +```bash +# Check all containers +docker ps + +# Check network connectivity +docker network inspect igny8_net + +# Test backend health +curl http://localhost:8011/api/v1/system/status/ + +# Test frontend +curl http://localhost:8021 +``` + +--- + +### Step 10: Initialize Database + +#### 10.1 Run Migrations + +```bash +# Execute migrations +docker exec igny8_backend python manage.py migrate + +# Create superuser (optional) +docker exec -it igny8_backend python manage.py createsuperuser +``` + +#### 10.2 Load Initial Data (if needed) + +```bash +# Load default plans, industries, etc. +docker exec igny8_backend python manage.py loaddata initial_data.json +``` + +--- + +### Step 11: Configure Caddy for HTTPS + +#### 11.1 Update Caddyfile + +Ensure Caddyfile includes: +- Domain names +- SSL certificate auto-generation +- Reverse proxy rules + +#### 11.2 Restart Caddy + +```bash +# Restart Caddy container +docker compose -f docker-compose.yml -p igny8-infra restart igny8_caddy + +# Check Caddy logs +docker logs igny8_caddy +``` + +--- + +### Step 12: Verify Installation + +#### 12.1 Check Service Status + +```bash +# Infrastructure services +docker compose -f docker-compose.yml -p igny8-infra ps + +# Application services +docker compose -f docker-compose.app.yml -p igny8-app ps + +# All services should show "Up" status +``` + +#### 12.2 Test Access + +1. **Marketing Site**: `https://igny8.com` (or `http://your-ip:8023` for dev) +2. **Main App**: `https://app.igny8.com` (or `http://your-ip:8021` for dev) +3. **Backend API**: `https://api.igny8.com/api/v1/system/status/` +4. **Portainer**: `http://your-ip:9000` +5. **pgAdmin**: `http://your-ip:5050` + +#### 12.3 Check Logs + +```bash +# Backend logs +docker logs igny8_backend + +# Frontend logs +docker logs igny8_frontend + +# Marketing logs +docker logs igny8_marketing_dev + +# Check for errors +docker logs igny8_backend 2>&1 | grep -i error +``` + +--- + +### Step 13: Post-Installation Configuration + +#### 13.1 Configure Integration Settings + +1. Access application: `https://app.igny8.com` +2. Sign up or log in +3. Navigate to Settings → Integration +4. Configure: + - OpenAI API key + - Runware API key (optional) + - WordPress credentials (per site) + +#### 13.2 Create First Site + +1. Navigate to Settings → Sites +2. Create a new site +3. Configure WordPress integration (if needed) +4. Create sectors (1-5 per site) + +#### 13.3 Set Up Monitoring (Optional) + +- Configure health checks +- Set up log rotation +- Configure backup scripts +- Set up monitoring alerts + +--- + +### Troubleshooting + +#### Common Issues + +**1. Port Already in Use**: +```bash +# Check what's using the port +sudo lsof -i :8011 +sudo lsof -i :8021 + +# Stop conflicting services or change ports in docker-compose +``` + +**2. Network Not Found**: +```bash +# Recreate network +docker network rm igny8_net +docker network create igny8_net + +# Restart services +docker compose -f docker-compose.app.yml -p igny8-app restart +``` + +**3. Database Connection Failed**: +```bash +# Check PostgreSQL is running +docker ps | grep postgres + +# Check network connectivity +docker exec igny8_backend ping postgres + +# Verify credentials in docker-compose +``` + +**4. Permission Denied**: +```bash +# Fix directory permissions +sudo chown -R $USER:$USER /data/app +sudo chmod -R 755 /data/app +``` + +**5. Caddy SSL Issues**: +```bash +# Check Caddy logs +docker logs igny8_caddy + +# Verify domain DNS points to server +nslookup igny8.com + +# Check firewall allows port 80/443 +sudo ufw status +``` + +--- + +### Maintenance Commands + +#### View Logs +```bash +# All services +docker compose -f docker-compose.app.yml -p igny8-app logs -f + +# Specific service +docker logs -f igny8_backend +``` + +#### Restart Services +```bash +# Restart all app services +docker compose -f docker-compose.app.yml -p igny8-app restart + +# Restart specific service +docker restart igny8_backend +``` + +#### Update Application +```bash +# Pull latest code +cd /data/app/igny8 +git pull + +# Rebuild images +docker build -t igny8-backend:latest -f backend/Dockerfile ./backend +docker build -t igny8-frontend-dev:latest -f frontend/Dockerfile.dev ./frontend + +# Restart services +docker compose -f docker-compose.app.yml -p igny8-app up -d +``` + +#### Backup Database +```bash +# Create backup +docker exec igny8_postgres pg_dump -U igny8 igny8_db > /data/backups/backup_$(date +%Y%m%d_%H%M%S).sql +``` + +--- + +### Security Checklist + +- [ ] Firewall configured (UFW) +- [ ] SSH key-based authentication enabled +- [ ] Strong passwords for all services +- [ ] Docker socket permissions secured +- [ ] Caddy HTTPS configured +- [ ] Environment variables secured +- [ ] Regular backups scheduled +- [ ] Log rotation configured +- [ ] Monitoring set up +- [ ] Security updates automated + +--- + +### Next Steps + +After installation: + +1. **Configure Domain**: Update DNS records and Caddy configuration +2. **Set Up Backups**: Configure automated database backups +3. **Monitor Logs**: Set up log aggregation and monitoring +4. **Performance Tuning**: Optimize Docker resources and database +5. **Security Hardening**: Review security settings and access controls + +--- + +## Summary + +The complete installation process includes: + +1. **Server Setup**: Ubuntu VPS preparation +2. **Docker Installation**: Docker Engine and Docker Compose +3. **Portainer Setup**: Container management UI +4. **Network Creation**: Docker network for services +5. **Infrastructure Stack**: PostgreSQL, Redis, Caddy, etc. +6. **Application Build**: Build Docker images +7. **Application Deployment**: Start application services +8. **Database Initialization**: Run migrations +9. **HTTPS Configuration**: Caddy SSL setup +10. **Verification**: Test all services + +This installation guide provides a complete path from a fresh Ubuntu server to a fully operational IGNY8 platform. + diff --git a/docs/02-APP-ARCHITECTURE.md b/docs/02-APPLICATION-ARCHITECTURE.md similarity index 99% rename from docs/02-APP-ARCHITECTURE.md rename to docs/02-APPLICATION-ARCHITECTURE.md index fca64dca..85b429c9 100644 --- a/docs/02-APP-ARCHITECTURE.md +++ b/docs/02-APPLICATION-ARCHITECTURE.md @@ -1,7 +1,7 @@ # IGNY8 Application Architecture **Last Updated:** 2025-01-XX -**Purpose:** Complete application architecture documentation covering system hierarchy, modules, workflows, features, and data flow. +**Purpose:** Complete application architecture documentation covering system hierarchy, user roles, access control, modules, workflows, data models, multi-tenancy, API architecture, and security. --- diff --git a/docs/03-FRONTEND-ARCHITECTURE.md b/docs/03-FRONTEND-ARCHITECTURE.md new file mode 100644 index 00000000..4e5265a9 --- /dev/null +++ b/docs/03-FRONTEND-ARCHITECTURE.md @@ -0,0 +1,1492 @@ +# IGNY8 Frontend Architecture Documentation + +**Last Updated:** 2025-01-XX +**Version:** 1.0 +**Purpose:** Master-level architecture and functional documentation for the IGNY8 frontend application, covering structure, routing, state management, build system, and all functional details. + +--- + +## Table of Contents + +1. [Executive Summary](#executive-summary) +2. [Prerequisites](#prerequisites) +3. [Technology Stack](#technology-stack) +4. [Application Architecture Overview](#application-architecture-overview) +5. [Project Structure](#project-structure) +6. [Dual Application Architecture](#dual-application-architecture) +7. [Routing Architecture](#routing-architecture) +8. [State Management](#state-management) +9. [Component Architecture](#component-architecture) +10. [Template System](#template-system) +11. [API Integration Layer](#api-integration-layer) +12. [Build System & Configuration](#build-system--configuration) +13. [Development Workflow](#development-workflow) +14. [Deployment Architecture](#deployment-architecture) +15. [Key Features & Functions](#key-features--functions) +16. [Performance Optimizations](#performance-optimizations) +17. [Security Considerations](#security-considerations) + +--- + +## Executive Summary + +The IGNY8 frontend is a modern, dual-application React-based system consisting of: + +1. **Main Application** (`app.igny8.com`): A full-featured SaaS platform for SEO content management with authentication, multi-tenancy, and complex workflows +2. **Marketing Site** (`igny8.com`): A public-facing marketing website with SEO-optimized pages + +Both applications share the same codebase but are built and deployed separately, using different entry points, routing, and build configurations. + +### Key Characteristics + +- **Framework**: React 19 with TypeScript +- **Build Tool**: Vite 6.1.0 +- **Styling**: Tailwind CSS 4.0 +- **State Management**: Zustand with persistence +- **Routing**: React Router v7 +- **Code Splitting**: Lazy loading for optimal performance +- **Architecture**: Component-based with template system + +--- + +## Prerequisites + +### Development Environment + +| Requirement | Version | Purpose | +|------------|---------|---------| +| **Node.js** | 18+ | JavaScript runtime | +| **npm** | 9+ | Package manager | +| **TypeScript** | 5.7+ | Type checking | +| **Docker** | 20+ | Containerization (optional) | +| **Git** | 2.30+ | Version control | + +### Runtime Dependencies + +| Dependency | Version | Purpose | +|------------|---------|---------| +| **React** | 19.0.0 | UI library | +| **React DOM** | 19.0.0 | DOM rendering | +| **React Router** | 7.9.5 | Client-side routing | +| **Zustand** | 5.0.8 | State management | +| **Vite** | 6.1.0 | Build tool & dev server | + +### External Services + +- **Backend API**: Django REST Framework API (default: `https://api.igny8.com/api`) +- **Authentication**: JWT-based (access + refresh tokens) +- **Reverse Proxy**: Caddy (for production HTTPS) + +--- + +## Technology Stack + +### Core Framework & Libraries + +```json +{ + "react": "^19.0.0", + "react-dom": "^19.0.0", + "react-router-dom": "^7.9.5", + "zustand": "^5.0.8", + "typescript": "~5.7.2" +} +``` + +### UI & Styling + +| Library | Version | Purpose | +|---------|---------|---------| +| **Tailwind CSS** | 4.0.8 | Utility-first CSS framework | +| **@heroicons/react** | 2.2.0 | Icon library | +| **clsx** | 2.1.1 | Conditional class names | +| **tailwind-merge** | 3.0.1 | Merge Tailwind classes | + +### Data Visualization + +| Library | Version | Purpose | +|---------|---------|---------| +| **apexcharts** | 4.1.0 | Chart library | +| **react-apexcharts** | 1.7.0 | React wrapper for ApexCharts | + +### Forms & Inputs + +| Library | Version | Purpose | +|---------|---------|---------| +| **flatpickr** | 4.6.13 | Date/time picker | +| **react-dropzone** | 14.3.5 | File upload component | +| **react-dnd** | 16.0.1 | Drag and drop | + +### SEO & Meta Tags + +| Library | Version | Purpose | +|---------|---------|---------| +| **react-helmet-async** | 2.0.5 | Dynamic head management | + +### Build & Development Tools + +| Tool | Version | Purpose | +|------|---------|---------| +| **Vite** | 6.1.0 | Build tool & dev server | +| **@vitejs/plugin-react** | 4.3.4 | React plugin for Vite | +| **vite-plugin-svgr** | 4.3.0 | SVG as React components | +| **ESLint** | 9.19.0 | Code linting | +| **TypeScript ESLint** | 8.22.0 | TypeScript linting | + +--- + +## Application Architecture Overview + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Frontend Application │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ Main Application │ │ Marketing Site │ │ +│ │ (app.igny8.com) │ │ (igny8.com) │ │ +│ ├──────────────────────┤ ├──────────────────────┤ │ +│ │ • Authentication │ │ • Public Pages │ │ +│ │ • Multi-tenant │ │ • SEO Optimized │ │ +│ │ • Protected Routes │ │ • No Authentication │ │ +│ │ • Complex Workflows │ │ • Static Content │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ │ │ +│ └──────────┬───────────────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Shared Components │ │ +│ │ & Utilities │ │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ API Service Layer │ │ +│ │ (services/api.ts) │ │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Backend API │ │ +│ │ (Django REST) │ │ +│ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Application Entry Points + +#### Main Application Entry +- **File**: `src/main.tsx` +- **HTML**: `index.html` +- **Port**: 5173 (dev), 8021 (Docker) +- **Domain**: `app.igny8.com` + +#### Marketing Site Entry +- **File**: `src/marketing/index.tsx` +- **HTML**: `marketing.html` +- **Port**: 5174 (dev), 8023 (Docker) +- **Domain**: `igny8.com` + +--- + +## Project Structure + +### Directory Hierarchy + +``` +frontend/ +├── public/ # Static assets +│ ├── favicon.png +│ └── images/ +├── src/ # Source code +│ ├── components/ # Reusable UI components +│ │ ├── auth/ # Authentication components +│ │ ├── charts/ # Chart components +│ │ ├── common/ # Common utilities +│ │ ├── dashboard/ # Dashboard-specific +│ │ ├── form/ # Form components +│ │ ├── header/ # Header components +│ │ ├── tables/ # Table components +│ │ ├── tasks/ # Task-related +│ │ ├── ui/ # Base UI components +│ │ └── UserProfile/ # User profile +│ ├── config/ # Configuration files +│ │ ├── forms/ # Form configurations +│ │ ├── pages/ # Page configurations +│ │ ├── routes.config.ts # Route metadata +│ │ └── snippets/ # Code snippets +│ ├── context/ # React contexts +│ │ ├── ThemeContext.tsx +│ │ ├── SidebarContext.tsx +│ │ └── HeaderMetricsContext.tsx +│ ├── hooks/ # Custom React hooks +│ ├── icons/ # Icon components +│ ├── layout/ # Layout components +│ │ ├── AppLayout.tsx # Main app layout +│ │ ├── AppHeader.tsx # Header component +│ │ └── AppSidebar.tsx # Sidebar navigation +│ ├── marketing/ # Marketing site +│ │ ├── components/ # Marketing components +│ │ ├── config/ # Marketing config +│ │ ├── data/ # Marketing data +│ │ ├── layout/ # Marketing layout +│ │ ├── pages/ # Marketing pages +│ │ ├ ├── Home.tsx +│ │ ├ ├── Product.tsx +│ │ ├ ├── Solutions.tsx +│ │ ├ ├── Pricing.tsx +│ │ └ └── ... +│ │ ├── styles/ # Marketing styles +│ │ ├── index.tsx # Marketing entry +│ │ └── MarketingApp.tsx # Marketing router +│ ├── pages/ # Main app pages +│ │ ├── AuthPages/ # Login/Signup +│ │ ├── Dashboard/ # Dashboard pages +│ │ ├── Planner/ # Planner module +│ │ ├── Writer/ # Writer module +│ │ ├── Thinker/ # Thinker module +│ │ ├── Billing/ # Billing module +│ │ ├── Settings/ # Settings pages +│ │ └── Help/ # Help pages +│ ├── services/ # API services +│ │ └── api.ts # Centralized API client +│ ├── store/ # Zustand stores +│ │ ├── authStore.ts # Authentication state +│ │ ├── siteStore.ts # Site management +│ │ ├── sectorStore.ts # Sector management +│ │ ├── plannerStore.ts # Planner state +│ │ ├── billingStore.ts # Billing state +│ │ └── ... +│ ├── styles/ # Global styles +│ │ ├── index.css # Main styles +│ │ └── igny8-colors.css # Custom colors +│ ├── templates/ # Page templates +│ │ ├── DashboardTemplate.tsx +│ │ ├── TablePageTemplate.tsx +│ │ ├── FormPageTemplate.tsx +│ │ ├── SystemPageTemplate.tsx +│ │ └── ContentViewTemplate.tsx +│ ├── utils/ # Utility functions +│ ├── App.tsx # Main app router +│ └── main.tsx # Main entry point +├── index.html # Main app HTML +├── marketing.html # Marketing HTML +├── vite.config.ts # Vite configuration +├── tsconfig.json # TypeScript config +├── package.json # Dependencies +└── Dockerfile* # Docker files +``` + +--- + +## Dual Application Architecture + +### Main Application (`app.igny8.com`) + +**Purpose**: Authenticated SaaS platform for content management + +**Characteristics**: +- Requires authentication (JWT tokens) +- Multi-tenant architecture +- Protected routes with role-based access +- Complex state management +- Real-time data updates +- Module-based organization (Planner, Writer, Thinker, Billing) + +**Entry Point**: `src/main.tsx` → `src/App.tsx` + +**Provider Hierarchy**: +```typescript + + + + + + + + + + + +``` + +**Global Components**: +- `GlobalErrorDisplay` - Displays global errors +- `LoadingStateMonitor` - Tracks loading states +- `ScrollToTop` - Scrolls to top on route change +- `ProtectedRoute` - Route protection wrapper + +**Key Features**: +- User authentication & authorization +- Site & sector management +- Keyword management (Planner) +- Content generation (Writer) +- AI configuration (Thinker) +- Billing & credits +- Settings & integrations + +### Marketing Site (`igny8.com`) + +**Purpose**: Public-facing marketing website + +**Characteristics**: +- No authentication required +- Static content with SEO optimization +- Simple routing +- Minimal state management +- Fast loading times +- SEO meta tags + +**Entry Point**: `src/marketing/index.tsx` → `src/marketing/MarketingApp.tsx` + +**Pages**: +- `/` - Home +- `/product` - Product overview +- `/solutions` - Solutions by industry +- `/pricing` - Pricing plans +- `/tour` - Product tour +- `/resources` - Resources & guides +- `/case-studies` - Case studies +- `/partners` - Partner program +- `/contact` - Contact page +- `/waitlist` - Waitlist signup + +**SEO Features**: +- Dynamic meta tags via `react-helmet-async` +- SEO component for each page +- Optimized meta descriptions +- Open Graph tags +- Twitter Card tags + +--- + +## Routing Architecture + +### Main Application Routing + +**Router**: React Router v7 (`BrowserRouter`) + +**Structure**: +```typescript + + + {/* Public Routes */} + } /> + } /> + + {/* Protected Routes */} + }> + } /> + + {/* Planner Module */} + } /> + } /> + } /> + } /> + } /> + + {/* Writer Module */} + } /> + } /> + } /> + } /> + } /> + } /> + } /> + + {/* Thinker Module */} + } /> + } /> + } /> + } /> + } /> + } /> + + {/* Billing Module */} + } /> + } /> + } /> + + {/* Reference Data */} + } /> + } /> + + {/* Automation & Schedules */} + } /> + } /> + + {/* Settings */} + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + + {/* Help */} + } /> + } /> + } /> + } /> + + {/* UI Elements Showcase */} + } /> + } /> + } /> + + {/* Fallback */} + } /> + + + +``` + +**Route Protection**: +- `ProtectedRoute` component checks authentication +- Redirects to `/signin` if not authenticated +- Validates JWT token on route access + +**Lazy Loading**: +- All page components are lazy-loaded using `React.lazy()` +- Reduces initial bundle size +- Improves time-to-interactive + +### Marketing Site Routing + +**Router**: React Router v7 (`BrowserRouter`) + +**Structure**: +```typescript + + + + + } /> + } /> + } /> + {/* ... more routes ... */} + + + +``` + +**SPA Routing**: +- Client-side routing for all pages +- Server configuration (Caddy/Vite) serves `marketing.html` for all routes +- Enables direct URL access and browser navigation + +**ScrollToTop Component**: +- Automatically scrolls to top on route change +- Ensures proper navigation experience + +--- + +## State Management + +### Zustand Architecture + +**Library**: Zustand 5.0.8 with persistence middleware + +**Store Structure**: +``` +store/ +├── authStore.ts # Authentication & user +├── siteStore.ts # Active site management +├── sectorStore.ts # Active sector management +├── plannerStore.ts # Planner module state +├── billingStore.ts # Billing & credits +├── settingsStore.ts # Application settings +├── pageSizeStore.ts # Table pagination +└── columnVisibilityStore.ts # Table column visibility +``` + +### Context Providers + +**React Context Architecture**: + +The application uses React Context for cross-component state sharing: + +**1. ThemeContext** (`src/context/ThemeContext.tsx`): +- Manages light/dark theme +- Persists theme preference in localStorage +- Applies theme class to document root +- Provides `useTheme()` hook + +**2. SidebarContext** (`src/context/SidebarContext.tsx`): +- Manages sidebar state (expanded/collapsed, mobile open/closed) +- Tracks active menu items and submenus +- Provides `useSidebar()` hook +- Wrapped in `SidebarProvider` component + +**3. HeaderMetricsContext** (`src/context/HeaderMetricsContext.tsx`): +- Manages header metrics and statistics +- Provides metrics display functionality +- Used for dashboard KPIs and statistics + +**4. ToastProvider** (`src/components/ui/toast/ToastContainer.tsx`): +- Global toast notification system +- Provides `useToast()` hook +- Methods: `success()`, `error()`, `warning()`, `info()` + +**Context Provider Hierarchy**: +```typescript + + + + + + + + + +``` + +### Custom Hooks + +**Hook Library** (`src/hooks/`): + +**1. useErrorHandler**: +- Global error handling system +- Tracks errors with source and timestamp +- Provides `addError()`, `clearError()`, `clearAllErrors()` +- Maintains last 10 errors + +**2. usePageDataLoader**: +- Standardized data loading pattern +- Handles loading states and errors +- Auto-load and manual load modes +- Dependency-based reloading + +**3. useModal**: +- Modal state management +- Open/close functionality +- Modal data management + +**4. useGoBack**: +- Navigation history management +- Back button functionality + +**5. usePersistentToggle**: +- Toggle state with localStorage persistence +- Remembers user preferences + +**6. useProgressModal**: +- Progress tracking for long operations +- Multi-step progress display + +**7. useResourceDebug**: +- Resource tracking and debugging +- Development/debugging utilities + +### Store Patterns + +#### Authentication Store (`authStore.ts`) + +**State**: +```typescript +interface AuthState { + user: User | null; + token: string | null; + refreshToken: string | null; + isAuthenticated: boolean; + loading: boolean; +} +``` + +**Actions**: +- `login(email, password)` - Authenticate user +- `logout()` - Clear authentication +- `register(data)` - Create new account +- `refreshToken()` - Refresh JWT token +- `refreshUser()` - Update user data + +**Persistence**: LocalStorage (`auth-storage`) + +#### Site Store (`siteStore.ts`) + +**State**: +```typescript +interface SiteState { + sites: Site[]; + activeSite: Site | null; + loading: boolean; +} +``` + +**Actions**: +- `loadSites()` - Fetch all sites +- `loadActiveSite()` - Load current active site +- `setActiveSite(site)` - Switch active site +- `createSite(data)` - Create new site +- `updateSite(id, data)` - Update site +- `deleteSite(id)` - Delete site + +**Persistence**: LocalStorage (`site-storage`) + +#### Sector Store (`sectorStore.ts`) + +**State**: +```typescript +interface SectorState { + sectors: Sector[]; + activeSector: Sector | null; + loading: boolean; +} +``` + +**Actions**: +- `loadSectorsForSite(siteId)` - Load sectors for site +- `setActiveSector(sector)` - Switch active sector +- `createSector(data)` - Create new sector +- `updateSector(id, data)` - Update sector +- `deleteSector(id)` - Delete sector +- `clearActiveSector()` - Clear active sector + +**Persistence**: LocalStorage (`sector-storage`) + +#### Settings Store (`settingsStore.ts`) + +**State**: +```typescript +interface SettingsState { + accountSettings: Record; + moduleSettings: Record>; + loading: boolean; + error: string | null; +} +``` + +**Actions**: +- `loadAccountSettings()` - Load all account settings +- `loadAccountSetting(key)` - Load specific account setting +- `updateAccountSetting(key, value)` - Update account setting +- `loadModuleSettings(moduleName)` - Load module settings +- `updateModuleSetting(moduleName, key, value)` - Update module setting +- `reset()` - Reset store state + +**Persistence**: LocalStorage (`settings-storage`) + +#### Page Size Store (`pageSizeStore.ts`) + +**State**: +```typescript +interface PageSizeStore { + pageSizes: Record; + setPageSize: (key: string, size: number) => void; + getPageSize: (key: string) => number; +} +``` + +**Purpose**: Manages pagination page sizes per table/page +**Persistence**: LocalStorage (`page-size-storage`) + +#### Column Visibility Store (`columnVisibilityStore.ts`) + +**State**: +```typescript +interface ColumnVisibilityState { + visibleColumns: Record; + setVisibleColumns: (key: string, columns: string[]) => void; + toggleColumn: (key: string, column: string) => void; +} +``` + +**Purpose**: Manages table column visibility preferences +**Persistence**: LocalStorage (`column-visibility-storage`) + +### Store Usage Pattern + +```typescript +// In components +import { useAuthStore } from '../store/authStore'; +import { useSiteStore } from '../store/siteStore'; + +function MyComponent() { + const { user, isAuthenticated } = useAuthStore(); + const { activeSite, setActiveSite } = useSiteStore(); + + // Component logic +} +``` + +--- + +## Component Architecture + +### Component Hierarchy + +``` +App +├── ErrorBoundary +├── ThemeProvider +├── HeaderMetricsProvider +├── ToastProvider +└── Router + ├── GlobalErrorDisplay + ├── LoadingStateMonitor + └── Routes + ├── Public Routes (SignIn, SignUp) + └── Protected Routes + └── AppLayout + ├── AppHeader + ├── AppSidebar + └── Outlet (Page Content) + └── Page Components + └── Template Components + └── UI Components +``` + +### Component Categories + +#### 1. Layout Components (`src/layout/`) + +**AppLayout.tsx**: +- Main application layout wrapper +- Manages sidebar, header, and content area +- Handles site/sector initialization +- Provides context for child components + +**Key Features**: +- **Site Initialization**: Automatically loads active site on mount +- **Sector Loading**: Loads sectors when active site changes +- **User Refresh**: Periodic user data refresh (every 2 minutes, on visibility change, on focus) +- **Version Detection**: Detects app version changes and refreshes user data +- **Timeout Handling**: 35-second timeout for site/sector loading +- **Error Handling**: Integrated error handling with useErrorHandler +- **Debug Overlay**: Resource tracking overlay (enabled via localStorage flag) +- **Loading State Tracking**: Integrates with LoadingStateMonitor +- **Responsive Layout**: Adapts to sidebar state (expanded/collapsed, mobile) + +**AppHeader.tsx**: +- Top navigation bar +- User menu, notifications, site selector +- Breadcrumbs and page title + +**AppSidebar.tsx**: +- Left navigation menu +- Module navigation (Planner, Writer, Thinker, Billing) +- Collapsible/expandable +- Mobile-responsive + +#### 2. Page Components (`src/pages/`) + +**Organization**: +- Module-based folders (Planner/, Writer/, Thinker/, Billing/) +- Feature-based pages within modules +- Shared pages (Dashboard/, Settings/, Help/) + +**Pattern**: +- Pages use templates for consistent structure +- Pages handle data fetching and business logic +- Pages compose UI components + +#### 3. Template Components (`src/templates/`) + +**DashboardTemplate.tsx**: +- Module dashboard pages +- KPI cards, workflow steps, charts +- Recent activity sections + +**TablePageTemplate.tsx**: +- CRUD table pages +- Filtering, sorting, pagination +- Bulk actions, export +- Column visibility controls + +**FormPageTemplate.tsx**: +- Settings and form pages +- Sectioned forms +- Save/cancel actions +- Validation display + +**SystemPageTemplate.tsx**: +- System/admin pages +- Status cards, logs, monitoring +- System information + +**ContentViewTemplate.tsx**: +- Individual content view +- Metadata display +- Content rendering + +#### 4. UI Components (`src/components/ui/`) + +**Base Components**: +- Button, Input, Select, Checkbox, Radio +- Table, Modal, Dropdown, Toast +- Card, Badge, Avatar, Spinner +- Pagination, Tabs, Tooltip + +**Pattern**: Reusable, styled with Tailwind CSS + +#### 5. Common Components (`src/components/common/`) + +**Utilities**: +- ScrollToTop - Route change scroll +- GlobalErrorDisplay - Error handling +- LoadingStateMonitor - Loading states +- ErrorBoundary - React error boundaries +- ColumnSelector - Table column management + +--- + +## Template System + +### Template Architecture + +The application uses 4 universal templates for consistent page structure: + +#### 1. DashboardTemplate + +**Purpose**: Module home pages + +**Features**: +- KPI cards with metrics +- Workflow step indicators +- Charts and visualizations +- Recent activity feeds + +**Usage**: +```typescript + +``` + +#### 2. TablePageTemplate + +**Purpose**: CRUD table pages + +**Features**: +- Data table with sorting +- Filtering and search +- Pagination +- Bulk actions +- Export functionality +- Column visibility controls + +**Usage**: +```typescript + +``` + +#### 3. FormPageTemplate + +**Purpose**: Settings and form pages + +**Features**: +- Sectioned form layout +- Field grouping +- Save/cancel actions +- Validation display +- Loading states + +**Usage**: +```typescript + +``` + +#### 4. SystemPageTemplate + +**Purpose**: System/admin pages + +**Features**: +- Status cards +- Log displays +- System metrics +- Monitoring dashboards + +**Usage**: +```typescript + +``` + +--- + +## API Integration Layer + +### API Service Architecture + +**File**: `src/services/api.ts` + +**Purpose**: Centralized API client with automatic configuration + +### API Configuration + +**Base URL Detection**: +```typescript +function getApiBaseUrl(): string { + // 1. Check environment variables + const envUrl = import.meta.env.VITE_BACKEND_URL; + if (envUrl) return envUrl; + + // 2. Auto-detect from origin + const origin = window.location.origin; + + // 3. Localhost/IP detection + if (origin.includes('localhost')) { + return origin.replace(':3000', ':8011') + '/api'; + } + + // 4. Production default + return 'https://api.igny8.com/api'; +} +``` + +**Authentication**: +- JWT tokens from Zustand store +- Automatic token injection in headers +- Token refresh on 401 responses +- Site/sector context injection + +### API Functions + +**Pattern**: Module-based function organization + +**Example Structure**: +```typescript +// Keywords API +export const keywordsApi = { + list: (params) => fetch('/api/v1/planner/keywords/', { params }), + create: (data) => fetch('/api/v1/planner/keywords/', { method: 'POST', body: data }), + update: (id, data) => fetch(`/api/v1/planner/keywords/${id}/`, { method: 'PATCH', body: data }), + delete: (id) => fetch(`/api/v1/planner/keywords/${id}/`, { method: 'DELETE' }), +}; + +// Content API +export const contentApi = { + list: (params) => fetch('/api/v1/writer/content/', { params }), + create: (data) => fetch('/api/v1/writer/content/', { method: 'POST', body: data }), + // ... more functions +}; +``` + +**Request Interceptors**: +- Automatic site/sector context injection +- JWT token attachment +- Error handling +- Loading state management + +**Response Handling**: +- JSON parsing +- Error extraction +- Status code handling +- Token refresh on 401 + +--- + +## Build System & Configuration + +### Vite Configuration + +**File**: `vite.config.ts` + +**Key Features**: + +#### 1. Dual Build Support + +```typescript +const isMarketingBuild = mode === "marketing"; + +build: { + rollupOptions: { + input: isMarketingBuild + ? { marketing: resolve(__dirname, "marketing.html") } + : { + main: resolve(__dirname, "index.html"), + marketing: resolve(__dirname, "marketing.html"), + }, + }, +} +``` + +#### 2. Code Splitting + +- Automatic code splitting by route +- Lazy-loaded components +- Vendor chunk separation +- CSS code splitting + +#### 3. Development Server + +**Main App** (Port 5173): +- Hot Module Replacement (HMR) +- WebSocket for live updates +- Proxy configuration for API + +**Marketing Site** (Port 5174): +- SPA routing plugin +- Marketing-specific configuration +- SEO-friendly development + +#### 4. Custom Plugins + +**bypassHostCheck**: +- Workaround for Vite 6.1.0 host check bug +- Allows external connections in Docker + +**serveMarketingSPA**: +- SPA routing for marketing dev server +- Serves `marketing.html` for all routes +- Enables direct URL access + +#### 5. Optimization + +**Dependency Pre-bundling**: +- Frequently used dependencies pre-bundled +- Heavy dependencies excluded (lazy-loaded) +- ESBuild for fast bundling + +**Build Optimization**: +- Minification with ESBuild +- Source maps in dev only +- Chunk size warnings +- Compressed size reporting + +### TypeScript Configuration + +**Files**: +- `tsconfig.json` - Base configuration +- `tsconfig.app.json` - Application config +- `tsconfig.node.json` - Node/build config + +**Settings**: +- Strict type checking +- ES2020 target +- React JSX support +- Path aliases + +### Environment Variables + +**Development**: +```bash +VITE_BACKEND_URL=https://api.igny8.com/api +VITE_ALLOWED_HOSTS=igny8.com,localhost +``` + +**Production**: +- Set via Docker environment +- Caddy reverse proxy configuration +- Domain-based routing + +--- + +## Development Workflow + +### Local Development Setup + +#### 1. Install Dependencies + +```bash +cd frontend +npm install +``` + +#### 2. Start Development Server + +**Main Application**: +```bash +npm run dev +# Runs on http://localhost:5173 +``` + +**Marketing Site**: +```bash +npm run dev:marketing +# Runs on http://localhost:5174 +``` + +#### 3. Build for Production + +**Main Application**: +```bash +npm run build +# Output: dist/ +``` + +**Marketing Site**: +```bash +npm run build:marketing +# Output: dist/marketing.html +``` + +### Docker Development + +#### Main App Container + +```bash +# Build image +docker build -t igny8-frontend-dev -f Dockerfile.dev frontend/ + +# Run container +docker run -p 8021:5173 \ + -v $(pwd)/frontend:/app \ + -e VITE_BACKEND_URL=https://api.igny8.com/api \ + igny8-frontend-dev +``` + +#### Marketing Container + +```bash +# Build image +docker build -t igny8-marketing-dev -f Dockerfile.marketing.dev frontend/ + +# Run container +docker run -p 8023:5174 \ + -v $(pwd)/frontend:/app \ + igny8-marketing-dev +``` + +### Development Scripts + +| Script | Command | Purpose | +|--------|---------|---------| +| `dev` | `vite` | Start main app dev server | +| `dev:marketing` | `PORT=5174 vite --port 5174` | Start marketing dev server | +| `build` | `vite build` | Build main app | +| `build:marketing` | `vite build --mode marketing` | Build marketing site | +| `type-check` | `tsc -b --noEmit` | Type checking | +| `lint` | `eslint .` | Lint code | + +--- + +## Deployment Architecture + +### Production Build + +#### Main Application + +**Build Output**: +``` +dist/ +├── index.html +├── assets/ +│ ├── js/ +│ │ ├── main-[hash].js +│ │ └── vendor-[hash].js +│ └── css/ +│ └── main-[hash].css +└── marketing.html (optional) +``` + +**Deployment**: +- Served via Caddy reverse proxy +- Static file serving +- SPA routing fallback + +#### Marketing Site + +**Build Output**: +``` +dist/ +├── marketing.html +├── assets/ +│ ├── js/ +│ │ └── marketing-[hash].js +│ └── css/ +│ └── marketing-[hash].css +``` + +**Deployment**: +- Separate Caddy configuration +- SPA routing enabled +- SEO optimization + +### Docker Deployment + +#### Production Dockerfile + +**Main App** (`Dockerfile`): +```dockerfile +FROM node:18-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm install +COPY . . +RUN npm run build + +FROM caddy:latest +COPY --from=builder /app/dist /usr/share/caddy +COPY Caddyfile /etc/caddy/Caddyfile +EXPOSE 8020 +CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"] +``` + +**Marketing** (`Dockerfile.marketing`): +```dockerfile +FROM node:18-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm install +COPY . . +RUN npm run build:marketing + +FROM caddy:latest +COPY --from=builder /app/dist /usr/share/caddy +COPY Caddyfile.marketing /etc/caddy/Caddyfile +EXPOSE 8020 +CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile"] +``` + +### Caddy Configuration + +#### Main App (`Caddyfile`) + +```caddy +:8020 { + root * /usr/share/caddy + encode gzip zstd + + # SPA routing + handle { + try_files {path} /index.html + file_server + } +} +``` + +#### Marketing Site (`Caddyfile.marketing`) + +```caddy +:8020 { + root * /usr/share/caddy + encode gzip zstd + + # SPA routing for marketing + handle { + try_files {path} /marketing.html + file_server + } +} +``` + +--- + +## Key Features & Functions + +### Authentication & Authorization + +**Features**: +- JWT-based authentication +- Access + refresh tokens +- Automatic token refresh +- Role-based access control (RBAC) +- Protected route guards + +**Implementation**: +- `ProtectedRoute` component +- `authStore` for state management +- API interceptors for token injection + +### Multi-Tenancy + +**Features**: +- Site-based isolation +- Sector organization within sites +- Active site/sector context +- Automatic context injection in API calls + +**Implementation**: +- `siteStore` and `sectorStore` +- Site/sector selectors in header +- Context-aware API functions + +### Module System + +**Modules**: +1. **Planner**: Keywords, clusters, ideas +2. **Writer**: Tasks, content, images +3. **Thinker**: Prompts, profiles, strategies +4. **Billing**: Credits, transactions, usage + +**Features**: +- Module-based routing +- Module-specific dashboards +- Module-specific stores +- Module-specific templates + +### Data Management + +**Features**: +- CRUD operations for all entities +- Filtering and sorting +- Pagination +- Bulk operations +- Export functionality +- Real-time updates + +**Implementation**: +- TablePageTemplate for lists +- API service layer +- Zustand stores for state + +### Error Handling + +**Features**: +- Global error boundary +- API error handling +- User-friendly error messages +- Error logging +- Retry mechanisms + +**Implementation**: +- `ErrorBoundary` component +- `GlobalErrorDisplay` component +- `useErrorHandler` hook +- API error interceptors + +### Loading States + +**Features**: +- Loading indicators +- Skeleton screens +- Progress tracking +- Loading state monitoring + +**Implementation**: +- `LoadingStateMonitor` component +- Loading states in stores +- Suspense boundaries + +--- + +## Performance Optimizations + +### Code Splitting + +**Strategy**: +- Route-based code splitting +- Lazy loading of page components +- Vendor chunk separation +- Dynamic imports for heavy dependencies + +**Implementation**: +```typescript +const Keywords = lazy(() => import("./pages/Planner/Keywords")); +``` + +### Bundle Optimization + +**Techniques**: +- Tree shaking +- Dead code elimination +- Minification (ESBuild) +- CSS code splitting +- Asset optimization + +### Runtime Performance + +**Optimizations**: +- Memoization with `useMemo` and `useCallback` +- Virtual scrolling for large lists +- Debounced search/filter +- Optimistic UI updates +- Request deduplication + +### Caching Strategy + +**Client-Side**: +- Zustand persistence (LocalStorage) +- API response caching +- Asset caching (browser cache) + +**Server-Side**: +- Static asset caching (Caddy) +- CDN for assets (if configured) + +--- + +## Security Considerations + +### Authentication Security + +**Measures**: +- JWT tokens stored securely +- Token refresh mechanism +- Automatic logout on token expiry +- Secure token transmission (HTTPS) + +### API Security + +**Measures**: +- HTTPS enforcement +- CORS configuration +- API key protection +- Request validation +- Rate limiting (backend) + +### Data Security + +**Measures**: +- No sensitive data in client code +- Secure storage of tokens +- XSS prevention +- CSRF protection (backend) +- Input sanitization + +### Content Security + +**Measures**: +- React's built-in XSS protection +- Sanitized user input +- Safe HTML rendering +- Secure file uploads + +--- + +## Conclusion + +The IGNY8 frontend architecture is designed for: + +1. **Scalability**: Modular structure supports growth +2. **Maintainability**: Clear separation of concerns +3. **Performance**: Optimized builds and lazy loading +4. **Developer Experience**: TypeScript, hot reload, clear patterns +5. **User Experience**: Fast loading, smooth navigation, responsive design + +The dual-application architecture allows for: +- Separate deployment of marketing and app +- Independent scaling +- Different optimization strategies +- Clear separation of public and authenticated content + +This architecture provides a solid foundation for continued development and scaling of the IGNY8 platform. + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-01-XX +**Maintained By**: IGNY8 Development Team + diff --git a/docs/03-FRONTEND.md b/docs/03-FRONTEND.md deleted file mode 100644 index 2f6684d1..00000000 --- a/docs/03-FRONTEND.md +++ /dev/null @@ -1,720 +0,0 @@ -# IGNY8 Frontend Documentation - -**Last Updated:** 2025-01-XX -**Purpose:** Complete frontend documentation covering architecture, pages, components, routing, state management, and configuration system. - ---- - -## Table of Contents - -1. [Frontend Overview](#frontend-overview) -2. [Tech Stack](#tech-stack) -3. [Project Structure](#project-structure) -4. [Routing System](#routing-system) -5. [Template System](#template-system) -6. [Component Library](#component-library) -7. [State Management](#state-management) -8. [API Integration](#api-integration) -9. [Configuration System](#configuration-system) -10. [Pages & Features](#pages--features) -11. [Hooks & Utilities](#hooks--utilities) - ---- - -## Frontend Overview - -The IGNY8 frontend is a React 19 application built with TypeScript, using Vite as the build tool and Tailwind CSS for styling. The frontend follows a configuration-driven architecture where UI components are rendered from configuration objects, eliminating code duplication and ensuring consistency. - -### Key Features - -- **Configuration-Driven UI**: All tables, filters, and forms driven by config files -- **4 Universal Templates**: DashboardTemplate, TablePageTemplate, FormPageTemplate, SystemPageTemplate -- **TypeScript**: Full type safety across the application -- **Zustand State Management**: Lightweight, performant state management -- **React Router v6**: Modern routing with nested routes -- **Responsive Design**: Mobile-first approach with Tailwind CSS - ---- - -## Tech Stack - -### Core Technologies - -- **React 19**: UI library -- **TypeScript**: Type safety -- **Vite**: Build tool and dev server -- **Tailwind CSS**: Utility-first CSS framework -- **React Router v6**: Client-side routing - -### State Management - -- **Zustand**: Lightweight state management library -- **localStorage**: Persistence for Zustand stores - -### HTTP Client - -- **Fetch API**: Native browser API with custom wrapper -- **Auto-retry**: Automatic retry on network failures -- **Token refresh**: Automatic JWT token refresh - -### UI Components - -- **Custom Component Library**: Built-in components (Button, Card, Modal, etc.) -- **Icons**: Custom icon library -- **Toast Notifications**: Toast notification system - ---- - -## Project Structure - -``` -frontend/src/ -├── pages/ # Page components -│ ├── Planner/ # Planner module pages -│ │ ├── Dashboard.tsx -│ │ ├── Keywords.tsx -│ │ ├── Clusters.tsx -│ │ ├── Ideas.tsx -│ │ ├── KeywordOpportunities.tsx -│ │ └── Mapping.tsx -│ ├── Writer/ # Writer module pages -│ │ ├── Dashboard.tsx -│ │ ├── Tasks.tsx -│ │ ├── Content.tsx -│ │ ├── ContentView.tsx -│ │ ├── Drafts.tsx -│ │ ├── Images.tsx -│ │ └── Published.tsx -│ ├── Thinker/ # Thinker module pages -│ │ ├── Dashboard.tsx -│ │ ├── Prompts.tsx -│ │ ├── AuthorProfiles.tsx -│ │ ├── Strategies.tsx -│ │ ├── Profile.tsx -│ │ └── ImageTesting.tsx -│ ├── Billing/ # Billing module pages -│ │ ├── Credits.tsx -│ │ ├── Transactions.tsx -│ │ └── Usage.tsx -│ ├── Settings/ # Settings pages -│ │ ├── General.tsx -│ │ ├── Users.tsx -│ │ ├── Sites.tsx -│ │ ├── Integration.tsx -│ │ ├── AI.tsx -│ │ ├── Plans.tsx -│ │ ├── Industries.tsx -│ │ ├── Status.tsx -│ │ ├── Subscriptions.tsx -│ │ ├── Account.tsx -│ │ ├── Modules.tsx -│ │ ├── System.tsx -│ │ ├── ImportExport.tsx -│ │ └── UiElements/ # UI element examples -│ ├── Help/ # Help pages -│ │ ├── Help.tsx -│ │ ├── Docs.tsx -│ │ ├── SystemTesting.tsx -│ │ └── FunctionTesting.tsx -│ ├── Reference/ # Reference data pages -│ │ ├── Industries.tsx -│ │ └── SeedKeywords.tsx -│ ├── AuthPages/ # Authentication pages -│ │ ├── SignIn.tsx -│ │ └── SignUp.tsx -│ ├── Dashboard/ # Main dashboard -│ │ └── Home.tsx -│ └── OtherPage/ # Other pages -│ └── NotFound.tsx -├── templates/ # 4 universal templates -│ ├── DashboardTemplate.tsx -│ ├── TablePageTemplate.tsx -│ ├── FormPageTemplate.tsx -│ └── SystemPageTemplate.tsx -├── components/ # UI components -│ ├── layout/ # Layout components -│ │ ├── AppLayout.tsx -│ │ ├── Sidebar.tsx -│ │ └── Header.tsx -│ ├── table/ # Table components -│ │ ├── DataTable.tsx -│ │ ├── Filters.tsx -│ │ └── Pagination.tsx -│ ├── ui/ # UI primitives -│ │ ├── button/ -│ │ ├── card/ -│ │ ├── modal/ -│ │ └── ... -│ └── auth/ # Auth components -│ └── ProtectedRoute.tsx -├── config/ # Configuration files -│ ├── pages/ # Page-specific configs -│ │ └── keywords.config.tsx -│ ├── snippets/ # Shared snippets -│ │ ├── columns.snippets.ts -│ │ ├── filters.snippets.ts -│ │ └── actions.snippets.ts -│ └── routes.config.ts # Route configuration -├── store/ # Zustand stores -│ ├── authStore.ts # Authentication state -│ ├── plannerStore.ts # Planner module state -│ ├── siteStore.ts # Site selection state -│ ├── sectorStore.ts # Sector selection state -│ ├── aiRequestLogsStore.ts # AI request/response logs -│ └── pageSizeStore.ts # Table page size preference -├── services/ # API clients -│ └── api.ts # fetchAPI, API functions -├── hooks/ # Custom React hooks -│ ├── useProgressModal.ts # Progress modal for long-running tasks -│ └── useAuth.ts # Authentication hook -├── utils/ # Utility functions -│ └── difficulty.ts # Difficulty utilities -├── App.tsx # Root component with routing -└── main.tsx # Entry point -``` - ---- - -## Routing System - -### Route Structure - -**Public Routes**: -- `/signin` - Sign in page -- `/signup` - Sign up page - -**Protected Routes** (require authentication): -- `/` - Home dashboard -- `/planner/*` - Planner module routes -- `/writer/*` - Writer module routes -- `/thinker/*` - Thinker module routes -- `/billing/*` - Billing module routes -- `/settings/*` - Settings routes -- `/help/*` - Help routes -- `/reference/*` - Reference data routes -- `/ui-elements/*` - UI element examples - -### ProtectedRoute Component - -**Purpose**: Wraps protected routes and checks authentication - -**Functionality**: -- Checks if user is authenticated -- Redirects to `/signin` if not authenticated -- Wraps children with `AppLayout` if authenticated - -### Route Configuration - -**File**: `config/routes.config.ts` - -**Structure**: Defines route hierarchy, labels, and icons for navigation - -**Functions**: -- `getBreadcrumbs(pathname)`: Generates breadcrumbs for current route - ---- - -## Template System - -### 1. DashboardTemplate - -**Purpose**: Module home pages with KPIs, workflow steps, and charts - -**Features**: -- Header metrics (KPIs) -- Workflow steps -- Charts and visualizations -- Quick actions - -**Usage**: Planner Dashboard, Writer Dashboard, Thinker Dashboard - -### 2. TablePageTemplate - -**Purpose**: CRUD table pages (Keywords, Clusters, Tasks, etc.) - -**Features**: -- Data table with sorting -- Filters (text, select, date range, custom) -- Pagination -- Bulk actions -- Row actions (edit, delete) -- AI Request/Response Logs section -- Import/Export functionality - -**Configuration**: -- `columns`: Column definitions (key, label, sortable, render, etc.) -- `filters`: Filter definitions (type, options, custom render) -- `bulkActions`: Bulk action definitions -- `actions`: Row action definitions - -**Usage**: Keywords, Clusters, Ideas, Tasks, Content, Images, Prompts, etc. - -### 3. FormPageTemplate - -**Purpose**: Settings/form pages (Settings, Integration, etc.) - -**Features**: -- Form sections -- Form validation -- Save/Cancel buttons -- Success/Error notifications - -**Usage**: Settings, Integration, AI Settings, Plans, etc. - -### 4. SystemPageTemplate - -**Purpose**: System/admin pages (Logs, Status, Monitoring) - -**Features**: -- System information display -- Logs viewer -- Status indicators -- Performance metrics - -**Usage**: System Status, System Testing, etc. - ---- - -## Component Library - -### Layout Components - -#### AppLayout -**Purpose**: Main app layout wrapper - -**Features**: -- Sidebar navigation -- Header with user menu -- Main content area -- Breadcrumbs - -#### Sidebar -**Purpose**: Navigation sidebar - -**Features**: -- Module navigation -- Active route highlighting -- Collapsible sections - -#### Header -**Purpose**: Top header bar - -**Features**: -- User menu -- Notifications -- Site/Sector selector - -### Table Components - -#### DataTable -**Purpose**: Data table component - -**Features**: -- Sortable columns -- Selectable rows -- Row actions -- Responsive design - -#### Filters -**Purpose**: Filter component - -**Features**: -- Text filters -- Select filters -- Date range filters -- Custom filters - -#### Pagination -**Purpose**: Pagination component - -**Features**: -- Page navigation -- Page size selector -- Total count display - -### UI Components - -#### Button -**Variants**: primary, secondary, danger, ghost, link -**Sizes**: sm, md, lg - -#### Card -**Purpose**: Card container component - -#### Modal -**Purpose**: Modal dialog component -**Variants**: FormModal, ProgressModal, AlertModal - -#### Toast -**Purpose**: Toast notification system -**Types**: success, error, warning, info - -#### Input -**Purpose**: Text input component - -#### Select -**Purpose**: Select dropdown component - -#### Checkbox -**Purpose**: Checkbox component - -### Auth Components - -#### ProtectedRoute -**Purpose**: Route protection component - -**Functionality**: -- Checks authentication -- Redirects to signin if not authenticated -- Wraps children with AppLayout - ---- - -## State Management - -### Zustand Stores - -#### authStore -**State**: -- `user`: Current user object -- `token`: JWT access token -- `refreshToken`: JWT refresh token -- `isAuthenticated`: Authentication status -- `loading`: Loading state - -**Actions**: -- `login(email, password)`: Sign in user -- `logout()`: Sign out user -- `register(data)`: Register new user -- `setUser(user)`: Set user object -- `setToken(token)`: Set access token -- `refreshToken()`: Refresh access token - -**Persistence**: localStorage (persisted) - -#### siteStore -**State**: -- `activeSite`: Currently selected site -- `sites`: List of accessible sites - -**Actions**: -- `setActiveSite(site)`: Set active site -- `loadSites()`: Load accessible sites - -**Persistence**: localStorage (persisted) - -#### sectorStore -**State**: -- `activeSector`: Currently selected sector -- `sectors`: List of sectors for active site - -**Actions**: -- `setActiveSector(sector)`: Set active sector -- `loadSectorsForSite(siteId)`: Load sectors for site - -**Persistence**: localStorage (persisted) - -#### plannerStore -**State**: Planner module-specific state - -**Actions**: Planner module actions - -#### aiRequestLogsStore -**State**: -- `logs`: Array of AI request/response logs - -**Actions**: -- `addLog(log)`: Add new log entry -- `addRequestStep(logId, step)`: Add request step to log -- `addResponseStep(logId, step)`: Add response step to log -- `updateLog(logId, data)`: Update log entry -- `clearLogs()`: Clear all logs - -**Purpose**: Tracks AI function execution with step-by-step logs - -#### pageSizeStore -**State**: -- `pageSize`: Table page size preference - -**Actions**: -- `setPageSize(size)`: Set page size - -**Persistence**: localStorage (persisted) - ---- - -## API Integration - -### API Service - -**File**: `services/api.ts` - -**Functions**: -- `fetchAPI(url, options)`: Generic API fetch wrapper -- `fetchKeywords(filters)`: Fetch keywords -- `createKeyword(data)`: Create keyword -- `updateKeyword(id, data)`: Update keyword -- `deleteKeyword(id)`: Delete keyword -- `bulkDeleteKeywords(ids)`: Bulk delete keywords -- `autoClusterKeywords(ids)`: Auto-cluster keywords -- `fetchClusters(filters)`: Fetch clusters -- `autoGenerateIdeas(clusterIds)`: Auto-generate ideas -- `fetchTasks(filters)`: Fetch tasks -- `autoGenerateContent(taskIds)`: Auto-generate content -- `autoGenerateImages(taskIds)`: Auto-generate images -- And more... - -**Features**: -- Automatic JWT token inclusion -- Automatic token refresh on 401 -- Auto-retry on network failures -- Error handling -- Request/response logging - -### API Base URL - -**Auto-detection**: -- Checks environment variables (`VITE_BACKEND_URL`, `VITE_API_URL`) -- Falls back to auto-detection based on current origin -- Supports localhost, IP addresses, and production subdomain - -**Default**: `https://api.igny8.com/api` - ---- - -## Configuration System - -### Page-Local Config - -**Location**: `config/pages/` - -**Example**: `keywords.config.tsx` - -**Structure**: Defines columns, filters, bulkActions, actions for a page - -**Usage**: Imported in page components to configure TablePageTemplate - -### Shared Snippets - -**Location**: `config/snippets/` - -#### columns.snippets.ts -**Purpose**: Reusable column definitions - -**Examples**: -- `statusColumn`: Status column with badge -- `titleColumn`: Title column with link -- `dateColumn`: Date column with formatting - -#### filters.snippets.ts -**Purpose**: Reusable filter definitions - -**Examples**: -- `statusFilter`: Status dropdown filter -- `dateRangeFilter`: Date range filter -- `searchFilter`: Text search filter - -#### actions.snippets.ts -**Purpose**: Reusable action definitions - -**Examples**: -- `commonActions`: Edit, Delete actions -- `bulkActions`: Bulk delete, bulk update actions - -### Route Configuration - -**File**: `config/routes.config.ts` - -**Structure**: Defines route hierarchy, labels, and icons for navigation - -**Functions**: -- `getBreadcrumbs(pathname)`: Generates breadcrumbs for current route - ---- - -## Pages & Features - -### Planner Module - -#### Keywords Page (`/planner/keywords`) -**Features**: -- Keyword CRUD operations -- Auto-cluster functionality -- Import/Export (CSV) -- Filters (status, cluster, intent, difficulty, volume) -- Bulk actions (delete, status update) -- AI Request/Response Logs - -**Configuration**: Uses `keywords.config.tsx` - -#### Clusters Page (`/planner/clusters`) -**Features**: -- Cluster CRUD operations -- Auto-generate ideas functionality -- Filters (status, sector) -- Bulk actions - -#### Ideas Page (`/planner/ideas`) -**Features**: -- Content ideas CRUD operations -- Filters (status, cluster, content type) -- Bulk actions - -#### Planner Dashboard (`/planner`) -**Features**: -- KPIs (total keywords, clusters, ideas) -- Workflow steps -- Charts and visualizations - -### Writer Module - -#### Tasks Page (`/writer/tasks`) -**Features**: -- Task CRUD operations -- Auto-generate content functionality -- Auto-generate images functionality -- Filters (status, cluster, content type) -- Bulk actions - -#### Content Page (`/writer/content`) -**Features**: -- Content list view -- Content detail view (`/writer/content/:id`) -- Content editing -- Generate image prompts -- Generate images -- WordPress publishing - -#### Images Page (`/writer/images`) -**Features**: -- Image list view -- Image generation -- Image management - -#### Writer Dashboard (`/writer`) -**Features**: -- KPIs (total tasks, content, images) -- Workflow steps -- Charts and visualizations - -### Thinker Module - -#### Prompts Page (`/thinker/prompts`) -**Features**: -- AI prompt CRUD operations -- Prompt type management -- Default prompt reset - -#### Author Profiles Page (`/thinker/author-profiles`) -**Features**: -- Author profile CRUD operations -- Writing style configuration - -#### Strategies Page (`/thinker/strategies`) -**Features**: -- Content strategy CRUD operations -- Strategy configuration - -#### Image Testing Page (`/thinker/image-testing`) -**Features**: -- Image generation testing -- Prompt testing -- Model testing - -### Billing Module - -#### Credits Page (`/billing/credits`) -**Features**: -- Credit balance display -- Credit purchase -- Credit history - -#### Transactions Page (`/billing/transactions`) -**Features**: -- Transaction history -- Transaction filtering - -#### Usage Page (`/billing/usage`) -**Features**: -- Usage logs -- Cost tracking -- Usage analytics - -### Settings Pages - -#### Sites Page (`/settings/sites`) -**Features**: -- Site CRUD operations -- Site activation/deactivation -- Multiple sites can be active simultaneously - -#### Integration Page (`/settings/integration`) -**Features**: -- Integration settings (OpenAI, Runware) -- API key configuration -- Test connections -- Image generation testing - -#### Users Page (`/settings/users`) -**Features**: -- User CRUD operations -- Role management -- Site access management - -#### AI Settings Page (`/settings/ai`) -**Features**: -- AI prompt management -- Model configuration - ---- - -## Hooks & Utilities - -### useProgressModal - -**Purpose**: Progress modal for long-running AI tasks - -**Features**: -- Displays progress percentage -- Shows phase messages -- Displays request/response steps -- Shows cost and token information -- Auto-closes on completion - -### useAuth - -**Purpose**: Authentication hook - -**Features**: -- Checks authentication status -- Provides user information -- Handles token refresh - -### Utilities - -#### difficulty.ts -**Purpose**: Difficulty calculation utilities - -**Functions**: -- Difficulty level calculation -- Difficulty formatting - ---- - -## Summary - -The IGNY8 frontend provides: - -1. **Configuration-Driven UI**: All pages rendered from configuration -2. **4 Universal Templates**: Reusable templates for all page types -3. **TypeScript**: Full type safety -4. **Zustand State Management**: Lightweight, performant state -5. **React Router v6**: Modern routing -6. **Component Library**: Comprehensive UI components -7. **API Integration**: Automatic token handling and retry -8. **Progress Tracking**: Real-time progress for AI tasks -9. **Responsive Design**: Mobile-first approach -10. **Complete Feature Set**: All modules and pages implemented - -This architecture ensures consistency, maintainability, and rapid feature development while providing a great user experience. - diff --git a/docs/04-BACKEND.md b/docs/04-BACKEND-IMPLEMENTATION.md similarity index 99% rename from docs/04-BACKEND.md rename to docs/04-BACKEND-IMPLEMENTATION.md index 19afb8f4..28fb93c8 100644 --- a/docs/04-BACKEND.md +++ b/docs/04-BACKEND-IMPLEMENTATION.md @@ -1,7 +1,7 @@ -# IGNY8 Backend Documentation +# IGNY8 Backend Implementation Reference **Last Updated:** 2025-01-XX -**Purpose:** Complete backend documentation covering models, views, APIs, modules, serializers, tasks, and structure. +**Purpose:** Complete backend implementation reference covering project structure, models, ViewSets, serializers, Celery tasks, API endpoints, base classes, middleware, and utilities. --- diff --git a/docs/05-AI-FUNCTIONS.md b/docs/05-AI-FRAMEWORK-IMPLEMENTATION.md similarity index 98% rename from docs/05-AI-FUNCTIONS.md rename to docs/05-AI-FRAMEWORK-IMPLEMENTATION.md index 4add200b..5ea10663 100644 --- a/docs/05-AI-FUNCTIONS.md +++ b/docs/05-AI-FRAMEWORK-IMPLEMENTATION.md @@ -1,7 +1,7 @@ -# IGNY8 AI Functions Documentation +# IGNY8 AI Framework Implementation Reference **Last Updated:** 2025-01-XX -**Purpose:** Complete AI functions documentation covering architecture, all 5 AI functions, execution flow, and configuration. +**Purpose:** Complete AI framework implementation reference covering architecture, code structure, all 5 AI functions, execution flow, progress tracking, cost tracking, prompt management, and model configuration. --- diff --git a/docs/06-CHANGELOG.md b/docs/06-CHANGELOG.md deleted file mode 100644 index aa157b50..00000000 --- a/docs/06-CHANGELOG.md +++ /dev/null @@ -1,173 +0,0 @@ -# IGNY8 Changelog - -**Last Updated:** 2025-01-XX -**Purpose:** System changelog documenting features, updates, and improvements. - ---- - -## Table of Contents - -1. [2025-01-XX - Documentation Consolidation](#2025-01-xx---documentation-consolidation) -2. [System Features](#system-features) -3. [Planned Features](#planned-features) - ---- - -## 2025-01-XX - Documentation Consolidation - -### Documentation Updates - -- **Consolidated Documentation**: All documentation consolidated into single structure - - `docs/README.md` - Documentation index - - `docs/01-ARCHITECTURE-TECH-STACK.md` - Architecture and tech stack - - `docs/02-APP-ARCHITECTURE.md` - Application architecture with workflows - - `docs/03-FRONTEND.md` - Frontend documentation - - `docs/04-BACKEND.md` - Backend documentation - - `docs/05-AI-FUNCTIONS.md` - AI functions documentation - - `docs/06-CHANGELOG.md` - System changelog - -### Improvements - -- **Complete Workflow Documentation**: All workflows documented from start to finish -- **Feature Completeness**: All features documented without missing any flows -- **No Code Snippets**: Documentation focuses on workflows and features (no code) -- **Accurate State**: Documentation reflects current system state - ---- - -## System Features - -### Implemented Features - -#### Foundation -- ✅ 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 v6 routing -- ✅ Progress tracking for AI tasks -- ✅ AI Request/Response Logs -- ✅ 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 - -#### 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 - ---- - -## Planned Features - -### In Progress - -- 🔄 Planner Dashboard enhancement with KPIs -- 🔄 WordPress integration (publishing) - partial implementation -- 🔄 Automation & CRON tasks - -### Future - -- 📋 Analytics module enhancements -- 📋 Advanced scheduling features -- 📋 Additional AI model integrations -- 📋 Stripe payment integration -- 📋 Plan limits enforcement -- 📋 Rate limiting -- 📋 Advanced reporting -- 📋 Mobile app support - ---- - -## Version History - -### Current Version - -**Version**: 1.0 -**Date**: 2025-01-XX -**Status**: Production - -### Key Milestones - -- **2025-01-XX**: Documentation consolidation -- **2025-01-XX**: AI framework implementation -- **2025-01-XX**: Multi-tenancy system -- **2025-01-XX**: Frontend configuration system -- **2025-01-XX**: Docker deployment setup - ---- - -## Notes - -- 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 - diff --git a/docs/06-FUNCTIONAL-BUSINESS-LOGIC.md b/docs/06-FUNCTIONAL-BUSINESS-LOGIC.md new file mode 100644 index 00000000..c2c0c65d --- /dev/null +++ b/docs/06-FUNCTIONAL-BUSINESS-LOGIC.md @@ -0,0 +1,1244 @@ +# IGNY8 Functional Business Logic Documentation + +**Last Updated:** 2025-01-XX +**Purpose:** Complete functional and business logic documentation covering all workflows, functions, features, and how the application works from a business perspective. + +--- + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [System Overview](#system-overview) +3. [Account and User Management](#account-and-user-management) +4. [Planner Module - Complete Workflows](#planner-module---complete-workflows) +5. [Writer Module - Complete Workflows](#writer-module---complete-workflows) +6. [Thinker Module - Complete Workflows](#thinker-module---complete-workflows) +7. [System Module - Complete Workflows](#system-module---complete-workflows) +8. [Billing Module - Complete Workflows](#billing-module---complete-workflows) +9. [AI Functions - Complete Details](#ai-functions---complete-details) +10. [Credit System - How It Works](#credit-system---how-it-works) +11. [WordPress Integration](#wordpress-integration) +12. [Data Flow and State Management](#data-flow-and-state-management) +13. [Complete Feature List](#complete-feature-list) + +--- + +## Prerequisites + +### Technology Stack Required + +**Backend Technologies:** +- Django +- Django REST Framework +- PostgreSQL +- Celery +- Redis +- Python + +**Frontend Technologies:** +- React +- TypeScript +- Vite +- Tailwind CSS +- Zustand +- React Router + +**Infrastructure:** +- Docker +- Docker Compose +- Caddy + +**External Services:** +- OpenAI API +- Runware API (optional) +- WordPress (optional) + +--- + +## System Overview + +IGNY8 is a SaaS platform for SEO keyword management and AI-driven content generation. The system operates on a multi-tenant architecture where each account is completely isolated. Users work within accounts, manage sites, organize content by sectors, and use AI to generate content from keywords. + +### Core Business Flow + +1. **Account Setup**: User creates account, sets up sites and sectors +2. **Keyword Management**: Import keywords, organize by sector, cluster related keywords +3. **Content Planning**: Generate content ideas from keyword clusters +4. **Content Creation**: Create tasks from ideas, generate AI content +5. **Image Generation**: Generate images for content +6. **Publishing**: Publish content to WordPress sites + +### Key Business Concepts + +- **Account**: Top-level organization containing all data +- **Site**: Workspace within account (can have multiple sites) +- **Sector**: Content category within site (1-5 per site) +- **Keywords**: SEO keywords organized by sector +- **Clusters**: AI-grouped related keywords +- **Content Ideas**: AI-generated content ideas from clusters +- **Tasks**: Content generation tasks created from ideas +- **Content**: Generated HTML blog posts and articles +- **Images**: AI-generated images for content +- **Credits**: Currency for AI operations + +--- + +## Account and User Management + +### Account Creation and Setup + +**Workflow:** +1. User visits signup page +2. User provides email and password +3. System creates Account record with default plan +4. System creates User record with "owner" role +5. System creates Subscription record linking account to plan +6. User receives confirmation +7. User signs in and receives JWT token +8. Frontend stores token and redirects to dashboard + +**Data Created:** +- Account record (name, slug, owner, plan, credits, status) +- User record (email, account, role: owner) +- Subscription record (account, plan, status) + +### User Roles and Permissions + +**Roles:** +- **Developer**: Full system access, bypasses all restrictions +- **Owner**: Full account access, manages users and billing +- **Admin**: Account admin, manages content and users +- **Editor**: Content editing access for granted sites only +- **Viewer**: Read-only access for granted sites only +- **System Bot**: System automation user + +**Access Control:** +- Owners and Admins: Automatic access to all sites in account +- Editors and Viewers: Require explicit site access grants +- Developers and System Bot: Access to all sites across all accounts + +### Site and Sector Management + +**Site Creation:** +1. User navigates to Settings → Sites +2. User creates site with name, domain, industry +3. System creates Site record linked to account +4. User can configure WordPress integration (URL, username, password) +5. Site becomes available for content organization + +**Sector Creation:** +1. User navigates to site details +2. User creates sector (1-5 active sectors per site) +3. System creates Sector record linked to site +4. Sector becomes available for keyword and content organization + +**Constraints:** +- Maximum 5 active sectors per site +- Multiple sites can be active simultaneously +- All content must belong to a site and sector + +--- + +## Planner Module - Complete Workflows + +### Keyword Management + +**Keyword Import (CSV):** +1. User navigates to Planner → Keywords +2. User clicks "Import CSV" action +3. User uploads CSV file with columns: keyword, volume, difficulty, intent +4. System validates CSV format and data +5. System checks for duplicates +6. System creates Keyword records for each row +7. Keywords are linked to selected site and sector +8. Keywords appear in table with status "active" + +**Keyword Import (Manual):** +1. User navigates to Planner → Keywords +2. User clicks "Add Keyword" action +3. User enters keyword, volume, difficulty, intent +4. System validates keyword uniqueness within sector +5. System creates Keyword record +6. Keyword appears in table + +**Keyword Filtering:** +- Filter by sector +- Filter by status (active, inactive, archived) +- Filter by intent (informational, navigational, transactional, commercial) +- Filter by cluster (clustered, unclustered) +- Filter by difficulty range (min/max) +- Filter by volume range (min/max) +- Search by keyword text + +**Keyword Bulk Operations:** +- Bulk delete: Select multiple keywords, delete all +- Bulk update status: Select multiple keywords, change status +- Bulk add from seed: Add keywords from seed keyword library + +**Keyword Export:** +1. User applies filters (optional) +2. User clicks "Export CSV" action +3. System generates CSV file with filtered keywords +4. User downloads CSV file + +### Keyword Clustering + +**Auto Cluster Workflow:** +1. User navigates to Planner → Keywords +2. User selects keywords (maximum 20 per batch) +3. User clicks "Auto Cluster" action +4. System validates keyword IDs and account credits +5. System queues Celery task (`run_ai_task` with function `auto_cluster`) +6. System returns task ID to frontend +7. Frontend polls progress endpoint (`/api/v1/system/settings/task_progress/{task_id}/`) +8. Celery worker processes task: + - Loads keywords from database + - Builds AI prompt with keyword data (keyword, volume, difficulty, intent) + - Calls OpenAI API with clustering prompt + - Parses AI response (cluster names and keyword assignments) + - Creates Cluster records for each cluster + - Links keywords to clusters (Many-to-Many relationship) + - Updates cluster metrics (keywords_count, volume) +9. Progress updates sent to frontend (phases: INIT, PREP, AI_CALL, PARSE, SAVE, DONE) +10. Task completes +11. Frontend displays new clusters +12. Credits deducted from account (1 credit per 30 keywords) + +**Manual Cluster Management:** +1. User navigates to Planner → Clusters +2. User views clusters with keyword counts and volumes +3. User can edit cluster name and description +4. User can add keywords to cluster +5. User can remove keywords from cluster +6. User can delete cluster (keywords remain, just unlinked) + +**Cluster Filtering:** +- Filter by sector +- Filter by status +- Search by cluster name +- Sort by keywords_count, volume, created_at + +### Content Idea Generation + +**Generate Ideas Workflow:** +1. User navigates to Planner → Clusters +2. User selects one cluster (maximum 1 per batch) +3. User clicks "Generate Ideas" action +4. System validates cluster ID and account credits +5. System queues Celery task (`run_ai_task` with function `generate_ideas`) +6. System returns task ID to frontend +7. Frontend polls progress endpoint +8. Celery worker processes task: + - Loads cluster and associated keywords + - Builds AI prompt with cluster data (cluster name, keywords, sector context) + - Calls OpenAI API with idea generation prompt + - Parses AI response (idea titles, descriptions, content types, structures) + - Creates ContentIdeas records for each idea + - Links ideas to cluster +9. Progress updates sent to frontend +10. Task completes +11. Frontend displays new content ideas +12. Credits deducted from account (1 credit per idea) + +**Content Ideas Management:** +1. User navigates to Planner → Ideas +2. User views ideas with titles, descriptions, content types +3. User can edit idea title and description +4. User can change idea status (active, inactive, archived) +5. User can delete idea +6. User can create tasks from ideas (moves to Writer module) + +**Idea Filtering:** +- Filter by sector +- Filter by cluster +- Filter by status +- Filter by content type +- Search by idea title + +**Bulk Queue to Writer:** +1. User selects multiple ideas +2. User clicks "Queue to Writer" action +3. System creates Task records for each idea +4. Tasks are linked to ideas and clusters +5. Tasks appear in Writer → Tasks page + +--- + +## Writer Module - Complete Workflows + +### Task Management + +**Task Creation:** +1. User navigates to Writer → Tasks +2. User can create task manually or from content ideas +3. If from ideas: System creates task with idea data (title, description, cluster, idea) +4. If manual: User enters title, description, selects cluster, content type, structure +5. System creates Task record +6. Task appears in table with status "draft" + +**Task Filtering:** +- Filter by sector +- Filter by cluster +- Filter by status (draft, in_progress, review, completed, archived) +- Filter by content type +- Filter by content structure +- Search by title or keywords + +**Task Bulk Operations:** +- Bulk delete: Select multiple tasks, delete all +- Bulk update status: Select multiple tasks, change status + +### Content Generation + +**Generate Content Workflow:** +1. User navigates to Writer → Tasks +2. User selects tasks (maximum 50 per batch) +3. User clicks "Generate Content" action +4. System validates task IDs and account credits +5. System queues Celery task (`run_ai_task` with function `generate_content`) +6. System returns task ID to frontend +7. Frontend polls progress endpoint +8. Celery worker processes task (for each task): + - Loads task and related data (cluster, keywords, idea, sector, site) + - Builds AI prompt with task data (title, description, keywords, content type, structure) + - Calls OpenAI API with content generation prompt + - Parses HTML content response + - Creates or updates Content record with HTML + - Calculates word count + - Updates task status to "review" +9. Progress updates sent to frontend (per task) +10. Task completes +11. Frontend displays generated content +12. Credits deducted from account (3 credits per content piece) + +**Content Management:** +1. User navigates to Writer → Content +2. User views content list with titles, word counts, status +3. User clicks content to view full HTML +4. User can edit content HTML directly +5. User can update content status (draft, review, published) +6. User can update meta title and description +7. User can update primary and secondary keywords + +**Content Filtering:** +- Filter by sector +- Filter by status +- Filter by content type +- Search by title or keywords +- Sort by word count, created_at, status + +**Content Views:** +- Drafts: Content with status "draft" +- Published: Content with status "published" and wp_post_id set +- All Content: All content regardless of status + +### Image Generation + +**Generate Image Prompts Workflow:** +1. User navigates to Writer → Content +2. User selects content items +3. User clicks "Generate Image Prompts" action (optional) +4. System validates content IDs +5. System queues Celery task (`run_ai_task` with function `generate_image_prompts`) +6. Celery worker processes task: + - Loads content HTML + - Builds AI prompt for image prompt extraction + - Calls OpenAI API + - Parses image prompts (featured image prompt, 1-6 in-article image prompts) + - Creates or updates Images records with prompts + - Sets image_type (featured, in_article) +7. Task completes +8. Images appear in Writer → Images page with prompts ready + +**Generate Images Workflow:** +1. User navigates to Writer → Images +2. User selects images with prompts +3. User clicks "Generate Images" action +4. System validates image IDs and account credits +5. System queues Celery task (`run_ai_task` with function `generate_images`) +6. System returns task ID to frontend +7. Frontend polls progress endpoint +8. Celery worker processes task (for each image sequentially): + - Loads image with prompt + - Determines image provider (OpenAI DALL-E or Runware) from integration settings + - Builds image generation request + - Calls OpenAI DALL-E API or Runware API + - Receives image URL + - Updates Images record with image_url + - Sets image status to "completed" +9. Progress updates sent to frontend (per image) +10. Task completes +11. Frontend displays generated images +12. Credits deducted from account (1 credit per image) + +**Image Management:** +1. User navigates to Writer → Images +2. User views images with prompts, URLs, types, status +3. User can view image by clicking +4. User can regenerate image (creates new image with same prompt) +5. User can delete image +6. User can update image status + +**Image Filtering:** +- Filter by content +- Filter by image type (featured, in_article, desktop, mobile) +- Filter by status +- Filter by task + +**Image Bulk Operations:** +- Bulk update status: Select multiple images, change status + +### WordPress Publishing + +**Publish to WordPress Workflow:** +1. User navigates to Writer → Content +2. User selects content to publish +3. User clicks "Publish to WordPress" action +4. System validates: + - Site has WordPress URL configured (wp_url field) + - Site has WordPress credentials (wp_username, wp_app_password) + - Content status is "review" or "draft" +5. System calls WordPress REST API: + - Authenticates with WordPress using credentials + - Creates post with content HTML (title from content meta_title or task title) + - Sets post content to content HTML + - Uploads featured image if available (Images record with image_type="featured") + - Uploads in-article images if available (Images records with image_type="in_article") + - Sets post status (draft or publish based on content status) + - Sets post meta (primary_keyword, secondary_keywords) +6. WordPress returns post ID +7. System updates Content record: + - Sets wp_post_id field + - Sets status to "published" +8. Frontend displays success message +9. User can view published content in WordPress + +**Publishing Requirements:** +- Site must have WordPress URL configured +- Site must have WordPress username and app password +- Content must have status "review" or "draft" +- Featured image is optional but recommended + +--- + +## Thinker Module - Complete Workflows + +### AI Prompts Management + +**Prompt Management:** +1. User navigates to Thinker → Prompts +2. User views all AI prompts used in the system +3. User can view prompt details (prompt_type, prompt_value, function_name) +4. User can edit prompt value +5. User can reset prompt to default value +6. System uses prompts in AI function execution + +**Prompt Types:** +- `auto_cluster`: Prompt for keyword clustering +- `generate_ideas`: Prompt for content idea generation +- `generate_content`: Prompt for content generation +- `generate_image_prompts`: Prompt for extracting image prompts from content +- `generate_images`: Prompt for image generation + +**Prompt Hierarchy:** +1. Account-specific prompt (if exists) +2. Default system prompt (fallback) + +### Author Profiles Management + +**Author Profile Creation:** +1. User navigates to Thinker → Author Profiles +2. User clicks "Add Profile" action +3. User enters name, description, tone, language +4. System creates AuthorProfile record +5. Profile becomes available for content generation + +**Author Profile Usage:** +- Author profiles are used in content generation prompts +- Profile tone and language influence AI-generated content style +- Multiple profiles can be created for different content styles + +**Author Profile Management:** +- View all profiles +- Edit profile details +- Delete profile + +### Strategies Management + +**Strategy Creation:** +1. User navigates to Thinker → Strategies +2. User clicks "Add Strategy" action +3. User enters name, description +4. User selects sector (optional, for sector-specific strategies) +5. User configures prompt types (which prompts this strategy affects) +6. User configures section logic (content structure preferences) +7. System creates Strategy record +8. Strategy becomes active and influences AI generation + +**Strategy Usage:** +- Strategies influence content generation when linked to sectors +- Strategy prompt types override default prompts +- Strategy section logic affects content structure + +**Strategy Management:** +- View all strategies +- Edit strategy details +- Activate/deactivate strategy +- Delete strategy + +### Image Testing + +**Image Testing Workflow:** +1. User navigates to Thinker → Image Testing +2. User enters image prompt +3. User selects image provider (OpenAI DALL-E or Runware) +4. User clicks "Generate Test Image" action +5. System calls image generation API +6. System displays generated image +7. User can test different prompts and providers +8. No credits deducted for testing (or minimal test credits) + +--- + +## System Module - Complete Workflows + +### Integration Settings + +**OpenAI Integration Setup:** +1. User navigates to Settings → Integration +2. User selects "OpenAI" integration type +3. User enters OpenAI API key +4. User clicks "Test Connection" (optional) +5. System makes test API call to OpenAI +6. System returns connection status +7. User saves integration settings +8. System stores API key in IntegrationSettings record +9. OpenAI integration ready for AI functions + +**Runware Integration Setup:** +1. User navigates to Settings → Integration +2. User selects "Runware" integration type +3. User enters Runware API key +4. User selects Runware model (e.g., `runware:97@1`) +5. User clicks "Test Connection" (optional) +6. System makes test API call to Runware +7. System returns connection status +8. User saves integration settings +9. System stores API key and model in IntegrationSettings record +10. Runware integration ready for image generation + +**Integration Test Functions:** +- Test OpenAI: Makes test API call, returns success/failure +- Test Runware: Makes test API call, returns success/failure +- Generate Test Image: Generates test image using selected provider + +### System Settings + +**General Settings:** +- Account name and details +- Site management +- Sector management +- Industry selection + +**User Management:** +- Add users to account +- Assign roles (owner, admin, editor, viewer) +- Grant site access (for editors/viewers) +- Remove users + +**Module Settings:** +- Enable/disable modules +- Configure module-specific settings + +**AI Settings:** +- Configure AI model preferences +- Set default models per function +- Configure token limits +- Set cost tracking preferences + +### System Status and Monitoring + +**Status Endpoint:** +- System health check +- Database connectivity +- Redis connectivity +- Celery worker status +- Service availability + +**Request Metrics:** +- API request counts +- Response times +- Error rates +- Resource usage (CPU, memory, I/O) + +--- + +## Billing Module - Complete Workflows + +### Credit Management + +**Credit Balance:** +- Each account has a credit balance +- Credits are displayed in Billing → Credits page +- Credits are deducted for AI operations +- Credits can be added via transactions + +**Credit Transactions:** +1. User navigates to Billing → Transactions +2. User views all credit transactions +3. Transaction types: + - Purchase: Credits purchased + - Subscription: Credits from subscription renewal + - Refund: Credits refunded + - Deduction: Credits used for AI operations + - Adjustment: Manual credit adjustments +4. Each transaction shows amount, balance_after, description, timestamp + +**Credit Usage Logs:** +1. User navigates to Billing → Usage +2. User views detailed usage logs +3. Each log entry shows: + - Operation type (clustering, ideas, content, images, reparse) + - Credits used + - Cost in USD + - Model used + - Input/output tokens + - Related object (keyword, cluster, task) + - Timestamp +4. Logs are filterable by operation type, date range + +### Credit Costs + +**Credit Costs per Operation:** +- Clustering: 1 credit per 30 keywords (base: 1 credit) +- Ideas: 1 credit per idea (base: 1 credit) +- Content: 3 credits per content piece (base: 3 credits) +- Images: 1 credit per image (base: 1 credit) +- Reparse: 1 credit per reparse (base: 1 credit) + +**Credit Deduction Process:** +1. User initiates AI operation +2. System checks account credit balance +3. System calculates required credits based on operation type +4. If insufficient credits: Operation fails with error +5. If sufficient credits: Operation proceeds +6. After operation completes: Credits deducted via CreditService +7. CreditTransaction record created (deduction type) +8. CreditUsageLog record created with operation details +9. Account credit balance updated + +### Plan Management + +**Plan Features:** +- Each account is linked to a plan via subscription +- Plans define limits: + - Maximum users + - Maximum sites + - Maximum keywords + - Maximum clusters + - Maximum content ideas + - Maximum AI requests + - Maximum word count + - Maximum images + - Included credits per month + - Credits per month (if different from included) + +**Plan Limits Enforcement:** +- System checks plan limits before operations +- Operations fail if limits exceeded +- Limits are checked at: + - Keyword import + - Cluster creation + - Idea generation + - Content generation + - Image generation + +--- + +## AI Functions - Complete Details + +### AI Function Execution Flow + +**Unified Entry Point:** +- All AI functions use `run_ai_task` Celery task +- Function name passed as parameter (auto_cluster, generate_ideas, generate_content, generate_image_prompts, generate_images) +- Payload contains function-specific data +- Account ID passed for credit checking and account isolation + +**Execution Phases:** +1. **INIT**: Initialize function, validate payload +2. **PREP**: Load data from database, prepare for AI call +3. **AI_CALL**: Make API call to OpenAI or Runware +4. **PARSE**: Parse AI response, extract structured data +5. **SAVE**: Save results to database +6. **DONE**: Task complete, return results + +**Progress Tracking:** +- Progress updates sent via Celery task progress +- Frontend polls progress endpoint +- Progress shows current phase and percentage +- Progress shows items processed (e.g., "3 of 10 keywords clustered") + +**Error Handling:** +- Validation errors: Returned immediately +- API errors: Logged, error returned to frontend +- Insufficient credits: Operation fails before AI call +- Network errors: Retried with exponential backoff + +### Auto Cluster Function + +**Function Name:** `auto_cluster` + +**Purpose:** Group related keywords into semantic clusters using AI + +**Input:** +- Keyword IDs (list, maximum 20) +- Sector ID (optional) + +**Process:** +1. Load keywords from database +2. Build prompt with keyword data (keyword, volume, difficulty, intent) +3. Call OpenAI API with clustering prompt +4. Parse response (cluster names, keyword assignments) +5. Create Cluster records +6. Link keywords to clusters +7. Update cluster metrics + +**Output:** +- Cluster records created +- Keywords linked to clusters +- Cluster metrics updated (keywords_count, volume) + +**Credits:** 1 credit per 30 keywords + +### Generate Ideas Function + +**Function Name:** `generate_ideas` + +**Purpose:** Generate SEO-optimized content ideas from keyword clusters + +**Input:** +- Cluster IDs (list, maximum 1 per batch) + +**Process:** +1. Load cluster and associated keywords +2. Build prompt with cluster data (name, keywords, sector context) +3. Call OpenAI API with idea generation prompt +4. Parse response (idea titles, descriptions, content types, structures) +5. Create ContentIdeas records +6. Link ideas to cluster + +**Output:** +- ContentIdeas records created +- Ideas linked to clusters + +**Credits:** 1 credit per idea + +### Generate Content Function + +**Function Name:** `generate_content` + +**Purpose:** Generate article content from task ideas + +**Input:** +- Task IDs (list, maximum 50 per batch) + +**Process:** +1. Load tasks with relationships (cluster, keywords, idea, sector, site) +2. For each task: + - Build prompt with task data (title, description, keywords, content type, structure) + - Call OpenAI API with content generation prompt + - Parse HTML content response + - Create or update Content record + - Calculate word count + - Update task status +3. Process tasks sequentially or in parallel (configurable) + +**Output:** +- Content records created/updated with HTML +- Task status updated to "review" +- Word count calculated + +**Credits:** 3 credits per content piece + +### Generate Image Prompts Function + +**Function Name:** `generate_image_prompts` + +**Purpose:** Extract image prompts from content HTML + +**Input:** +- Content IDs (list) + +**Process:** +1. Load content HTML +2. Build prompt for image prompt extraction +3. Call OpenAI API +4. Parse response (featured image prompt, 1-6 in-article image prompts) +5. Create or update Images records with prompts +6. Set image_type (featured, in_article) + +**Output:** +- Images records created/updated with prompts +- Image types set + +**Credits:** Included in content generation (no separate charge) + +### Generate Images Function + +**Function Name:** `generate_images` + +**Purpose:** Generate images using OpenAI DALL-E or Runware + +**Input:** +- Image IDs (list) + +**Process:** +1. Load images with prompts +2. Determine image provider from integration settings +3. For each image: + - Build image generation request + - Call OpenAI DALL-E API or Runware API + - Receive image URL + - Update Images record with image_url + - Set status to "completed" +4. Process images sequentially + +**Output:** +- Images records updated with image URLs +- Image status updated + +**Credits:** 1 credit per image + +--- + +## Credit System - How It Works + +### Credit Balance Management + +**Account Credits:** +- Each account has a `credits` field (integer) +- Credits start at 0 or plan-included credits +- Credits are deducted for AI operations +- Credits can be added via transactions + +**Credit Checking:** +- Before AI operation: System checks if account has sufficient credits +- If insufficient: Operation fails with `InsufficientCreditsError` +- If sufficient: Operation proceeds + +**Credit Deduction:** +- After AI operation completes: Credits deducted via `CreditService.deduct_credits()` +- Account credits field updated +- CreditTransaction record created (type: deduction, amount: negative) +- CreditUsageLog record created with operation details + +**Credit Addition:** +- Via transactions: `CreditService.add_credits()` called +- Account credits field updated +- CreditTransaction record created (type: purchase/subscription/refund/adjustment, amount: positive) + +### Credit Transaction Types + +**Purchase:** +- User purchases credits +- Amount: Positive integer +- Description: "Credit purchase" +- Balance after: Account credits + purchase amount + +**Subscription:** +- Credits from subscription renewal +- Amount: Plan's included_credits or credits_per_month +- Description: "Subscription renewal credits" +- Balance after: Account credits + subscription credits + +**Refund:** +- Credits refunded to account +- Amount: Positive integer +- Description: "Credit refund" +- Balance after: Account credits + refund amount + +**Deduction:** +- Credits used for AI operations +- Amount: Negative integer +- Description: Operation-specific (e.g., "Content generation") +- Balance after: Account credits - deduction amount + +**Adjustment:** +- Manual credit adjustments by admin +- Amount: Positive or negative integer +- Description: Admin-provided reason +- Balance after: Account credits + adjustment amount + +### Credit Usage Logging + +**Operation Types:** +- `clustering`: Keyword clustering operations +- `ideas`: Content idea generation +- `content`: Content generation +- `images`: Image generation +- `reparse`: Content reparse operations + +**Log Details:** +- Operation type +- Credits used +- Cost in USD (calculated from API costs) +- Model used (e.g., "gpt-4", "dall-e-3") +- Input tokens (if available) +- Output tokens (if available) +- Related object type (keyword, cluster, task, content, image) +- Related object ID +- Metadata (additional context) + +--- + +## WordPress Integration + +### WordPress Configuration + +**Site-Level Configuration:** +- Each site can have WordPress integration configured +- Fields: `wp_url`, `wp_username`, `wp_app_password` +- Configuration stored in Site model + +**WordPress App Password:** +- WordPress requires app password (not regular password) +- App password generated in WordPress user settings +- App password used for REST API authentication + +### Publishing Process + +**Publishing Workflow:** +1. User selects content to publish +2. System validates WordPress configuration +3. System authenticates with WordPress REST API +4. System creates WordPress post: + - Title: Content meta_title or task title + - Content: Content HTML + - Status: Draft or Publish (based on content status) + - Featured image: Uploaded if available + - In-article images: Uploaded if available + - Meta fields: Primary keyword, secondary keywords +5. WordPress returns post ID +6. System updates Content record: + - Sets `wp_post_id` field + - Sets `status` to "published" +7. User can view published content in WordPress + +**Image Upload:** +- Featured image: Images record with `image_type="featured"` +- In-article images: Images records with `image_type="in_article"` +- Images uploaded to WordPress media library +- Image URLs updated in WordPress post + +**Publishing Requirements:** +- Site must have `wp_url` configured +- Site must have `wp_username` and `wp_app_password` +- Content must have status "review" or "draft" +- WordPress REST API must be accessible + +--- + +## Data Flow and State Management + +### Frontend State Management + +**Zustand Stores:** +- **Auth Store**: User authentication, JWT token, account info +- **Site Store**: Current site selection, accessible sites +- **Sector Store**: Current sector selection, accessible sectors +- **Planner Store**: Planner module state (keywords, clusters, ideas) +- **Writer Store**: Writer module state (tasks, content, images) +- **Billing Store**: Credit balance, transactions, usage logs +- **Settings Store**: User settings, preferences +- **Page Size Store**: Table page size preferences +- **Column Visibility Store**: Table column visibility preferences + +**React Contexts:** +- **Theme Context**: Dark/light theme +- **Sidebar Context**: Sidebar open/closed state +- **Header Metrics Context**: Header KPI metrics +- **Toast Context**: Toast notifications + +### API Communication + +**API Client:** +- Frontend uses Fetch API for HTTP requests +- Base URL: `/api/v1/` +- JWT token included in Authorization header +- Request/response format: JSON + +**Request Flow:** +1. User action in frontend +2. Frontend makes API request +3. Backend middleware extracts account from JWT +4. Backend ViewSet processes request +5. Backend returns JSON response +6. Frontend updates state +7. Frontend updates UI + +**Response Format:** +- Success: `{success: true, data: {...}, message: "..."}` +- Error: `{success: false, error: "...", errors: {...}}` +- Pagination: `{count: N, next: "...", previous: "...", results: [...]}` + +### Celery Task Flow + +**Task Queueing:** +1. User action triggers API request +2. Backend ViewSet action queues Celery task +3. Task ID returned to frontend +4. Frontend stores task ID + +**Progress Polling:** +1. Frontend polls progress endpoint every 2-3 seconds +2. Backend returns progress (phase, percentage, items processed) +3. Frontend updates progress UI +4. Polling continues until task completes + +**Task Completion:** +1. Celery worker completes task +2. Results saved to database +3. Progress endpoint returns completion status +4. Frontend stops polling +5. Frontend refreshes data +6. Frontend displays results + +--- + +## Complete Feature List + +### Planner Module Features + +**Keywords:** +- CSV import +- Manual keyword entry +- Keyword filtering (sector, status, intent, cluster, difficulty, volume) +- Keyword search +- Keyword sorting +- Bulk delete +- Bulk status update +- Bulk add from seed keywords +- CSV export +- Auto cluster (AI-powered clustering) +- Keyword-to-cluster linking +- Keyword metrics display (volume, difficulty, intent) + +**Clusters:** +- Cluster listing +- Cluster creation (manual) +- Cluster editing (name, description) +- Cluster deletion +- Keyword-to-cluster management (add/remove) +- Cluster metrics (keywords_count, volume) +- Auto generate ideas (AI-powered idea generation) +- Cluster filtering (sector, status) +- Cluster search + +**Content Ideas:** +- Idea listing +- Idea creation (manual) +- Idea editing (title, description) +- Idea deletion +- Idea status management +- Bulk queue to writer (create tasks from ideas) +- Idea filtering (sector, cluster, status, content type) +- Idea search + +**Keyword Opportunities:** +- Opportunity analysis +- Keyword gap analysis +- Competitive analysis + +### Writer Module Features + +**Tasks:** +- Task listing +- Task creation (manual or from ideas) +- Task editing (title, description, content type, structure) +- Task deletion +- Task status management +- Auto generate content (AI-powered content generation) +- Task filtering (sector, cluster, status, content type, structure) +- Task search +- Bulk delete +- Bulk status update + +**Content:** +- Content listing +- Content viewing (full HTML) +- Content editing (HTML editor) +- Content status management +- Meta title and description editing +- Primary and secondary keywords editing +- Word count display +- Publish to WordPress +- Content filtering (sector, status, content type) +- Content search +- Drafts view +- Published view + +**Images:** +- Image listing +- Image viewing +- Image creation (manual) +- Image editing (prompt, type) +- Image deletion +- Generate image prompts (AI-powered prompt extraction) +- Generate images (AI-powered image generation) +- Image filtering (content, type, status, task) +- Image bulk status update +- Image regeneration + +### Thinker Module Features + +**Prompts:** +- Prompt listing +- Prompt viewing +- Prompt editing +- Prompt reset to default +- Prompt type filtering + +**Author Profiles:** +- Profile listing +- Profile creation +- Profile editing +- Profile deletion +- Profile usage in content generation + +**Strategies:** +- Strategy listing +- Strategy creation +- Strategy editing +- Strategy activation/deactivation +- Strategy deletion +- Sector-specific strategies +- Strategy prompt type configuration +- Strategy section logic configuration + +**Image Testing:** +- Test image generation +- Prompt testing +- Provider testing (OpenAI DALL-E, Runware) +- Image preview + +### System Module Features + +**Integration Settings:** +- OpenAI integration setup +- Runware integration setup +- API key management +- Connection testing +- Test image generation +- Model selection (Runware) + +**Settings:** +- General settings +- Account settings +- User settings +- Module settings +- AI settings + +**User Management:** +- User listing +- User creation +- User editing +- User deletion +- Role assignment +- Site access management + +**Site Management:** +- Site listing +- Site creation +- Site editing +- Site deletion +- WordPress integration configuration +- Industry assignment + +**Sector Management:** +- Sector listing +- Sector creation +- Sector editing +- Sector deletion +- Sector activation/deactivation +- Maximum 5 active sectors per site + +### Billing Module Features + +**Credits:** +- Credit balance display +- Credit transaction history +- Credit usage logs +- Credit cost display per operation + +**Transactions:** +- Transaction listing +- Transaction filtering (type, date range) +- Transaction details +- Balance tracking + +**Usage:** +- Usage log listing +- Usage log filtering (operation type, date range) +- Cost tracking +- Token tracking +- Model usage tracking + +**Plans:** +- Plan listing +- Plan details +- Plan limits display +- Subscription management + +### Authentication Features + +**Sign Up:** +- Account creation +- User creation (owner role) +- Subscription creation (default plan) +- Email validation +- Password validation + +**Sign In:** +- Email/password authentication +- JWT token generation +- Token storage (localStorage) +- Account context loading + +**Password Management:** +- Password change +- Password reset (planned) + +**Session Management:** +- Token expiration handling +- Token refresh (planned) +- Logout + +### Dashboard Features + +**Home Dashboard:** +- Account overview +- KPI metrics +- Recent activity +- Quick actions + +**Module Dashboards:** +- Planner Dashboard: Keyword metrics, cluster metrics, idea metrics +- Writer Dashboard: Task metrics, content metrics, image metrics +- Thinker Dashboard: Prompt metrics, strategy metrics +- Billing Dashboard: Credit balance, usage metrics + +--- + +## Summary + +IGNY8 operates as a complete SaaS platform for SEO keyword management and AI-driven content generation. The system follows a clear business flow: + +1. **Setup**: Users create accounts, set up sites and sectors +2. **Planning**: Users import keywords, cluster them with AI, generate content ideas +3. **Creation**: Users create tasks from ideas, generate AI content, generate images +4. **Publishing**: Users publish content to WordPress sites +5. **Management**: Users manage credits, transactions, settings, and integrations + +All operations are account-isolated, credit-based, and AI-powered. The system provides complete workflows from keyword import to WordPress publishing, with comprehensive filtering, search, and bulk operations throughout. + diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 4b3b06ea..00000000 --- a/docs/README.md +++ /dev/null @@ -1,146 +0,0 @@ -# IGNY8 Documentation - -**Last Updated:** 2025-01-XX -**Purpose:** Complete documentation index for the IGNY8 platform. - ---- - -## 📚 Documentation Structure - -All documentation is organized in this single folder with the following structure: - -### Core Documentation - -1. **[01-ARCHITECTURE-TECH-STACK.md](./01-ARCHITECTURE-TECH-STACK.md)** - - Technology stack overview - - System architecture principles - - Infrastructure components - - External service integrations - -2. **[02-APP-ARCHITECTURE.md](./02-APP-ARCHITECTURE.md)** - - IGNY8 application architecture - - System hierarchy and relationships - - Module organization - - Complete workflows - - Data flow and processing - - Multi-tenancy architecture - - Security architecture - -3. **[03-FRONTEND.md](./03-FRONTEND.md)** - - Frontend architecture - - Project structure - - Routing system - - Template system - - Component library - - State management - - API integration - - Configuration system - - All pages and features - -4. **[04-BACKEND.md](./04-BACKEND.md)** - - Backend architecture - - Project structure - - Models and relationships - - ViewSets and API endpoints - - Serializers - - Celery tasks - - Middleware - - All modules (Planner, Writer, System, Billing, Auth) - -5. **[05-AI-FUNCTIONS.md](./05-AI-FUNCTIONS.md)** - - AI framework architecture - - All 5 AI functions (complete details) - - AI function execution flow - - Prompt management - - Model configuration - - Progress tracking - - Cost tracking - -6. **[06-CHANGELOG.md](./06-CHANGELOG.md)** - - System changelog - - Feature additions - - Updates and improvements - - Version history - ---- - -## 🚀 Quick Start - -1. **New to IGNY8?** Start with [01-ARCHITECTURE-TECH-STACK.md](./01-ARCHITECTURE-TECH-STACK.md) for technology overview -2. **Understanding the System?** Read [02-APP-ARCHITECTURE.md](./02-APP-ARCHITECTURE.md) for complete architecture -3. **Frontend Development?** See [03-FRONTEND.md](./03-FRONTEND.md) for all frontend details -4. **Backend Development?** See [04-BACKEND.md](./04-BACKEND.md) for all backend details -5. **Working with AI?** See [05-AI-FUNCTIONS.md](./05-AI-FUNCTIONS.md) for AI functions -6. **What's New?** Check [06-CHANGELOG.md](./06-CHANGELOG.md) for recent changes - ---- - -## 📋 Documentation Overview - -### System Capabilities - -- **Multi-Tenancy**: Complete account isolation with automatic filtering -- **Planner Module**: Keywords, Clusters, Content Ideas management -- **Writer Module**: Tasks, Content, Images generation and management -- **Thinker Module**: Prompts, Author Profiles, Strategies, Image Testing -- **System Module**: Settings, Integrations, AI Prompts -- **Billing Module**: Credits, Transactions, Usage Logs -- **AI Functions**: 5 AI operations (Auto Cluster, Generate Ideas, Generate Content, Generate Image Prompts, Generate Images) - -### Technology Stack - -- **Backend**: Django 5.2+ with Django REST Framework -- **Frontend**: React 19 with TypeScript and Vite -- **Database**: PostgreSQL 15 -- **Task Queue**: Celery with Redis -- **Deployment**: Docker-based containerization -- **Reverse Proxy**: Caddy (HTTPS) - ---- - -## 🔍 Finding Information - -### By Topic - -- **Architecture & Design**: [01-ARCHITECTURE-TECH-STACK.md](./01-ARCHITECTURE-TECH-STACK.md), [02-APP-ARCHITECTURE.md](./02-APP-ARCHITECTURE.md) -- **Frontend Development**: [03-FRONTEND.md](./03-FRONTEND.md) -- **Backend Development**: [04-BACKEND.md](./04-BACKEND.md) -- **AI Functions**: [05-AI-FUNCTIONS.md](./05-AI-FUNCTIONS.md) -- **Changes & Updates**: [06-CHANGELOG.md](./06-CHANGELOG.md) - -### By Module - -- **Planner**: See [02-APP-ARCHITECTURE.md](./02-APP-ARCHITECTURE.md) (Module Organization) and [04-BACKEND.md](./04-BACKEND.md) (Planner Module) -- **Writer**: See [02-APP-ARCHITECTURE.md](./02-APP-ARCHITECTURE.md) (Module Organization) and [04-BACKEND.md](./04-BACKEND.md) (Writer Module) -- **Thinker**: See [03-FRONTEND.md](./03-FRONTEND.md) (Thinker Pages) and [04-BACKEND.md](./04-BACKEND.md) (System Module) -- **System**: See [04-BACKEND.md](./04-BACKEND.md) (System Module) -- **Billing**: See [04-BACKEND.md](./04-BACKEND.md) (Billing Module) - ---- - -## 📝 Documentation Standards - -- **No Code**: Documentation focuses on workflows, features, and architecture (no code snippets) -- **Complete**: All workflows and features are documented -- **Accurate**: Documentation reflects current system state -- **Detailed**: Comprehensive coverage of all aspects - ---- - -## 🔄 Keeping Documentation Updated - -Documentation is updated when: -- New features are added -- Workflows change -- Architecture evolves -- Modules are modified - -**Last Review**: 2025-01-XX -**Next Review**: As system evolves - ---- - -## 📞 Support - -For questions or clarifications about the documentation, refer to the specific document or contact the development team. -