igny8/README.md

# IGNY8 Platform

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 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

## 📁 Project Structure

```
igny8/
├── backend/              # Django backend
│   ├── igny8_core/      # Django project
│   │   ├── 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
│   │   ├── services/    # API clients
│   │   ├── components/  # UI components
│   │   ├── config/      # Configuration files
│   │   └── stores/      # Zustand stores
│   ├── Dockerfile
│   ├── 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
│   └── API-COMPLETE-REFERENCE.md  # Complete unified API documentation
├── 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)

### Development Setup

1. **Navigate to the project directory:**
   ```bash
   cd /data/app/igny8
   ```

2. **Backend Setup:**
   ```bash
   cd backend
   pip install -r requirements.txt
   python manage.py migrate
   python manage.py createsuperuser
   python manage.py runserver
   ```

3. **Frontend Setup:**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

4. **Access:**
   - Frontend: http://localhost:5173
   - Backend API: http://localhost:8011/api/
   - Admin: http://localhost:8011/admin/

### Docker Setup

```bash
# Build images
docker build -f backend/Dockerfile -t igny8-backend ./backend
docker build -f frontend/Dockerfile.dev -t igny8-frontend-dev ./frontend

# Run with docker-compose
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, 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
- Automation & CRON tasks
- Advanced analytics

### 🔄 Planned

- Analytics module enhancements
- Advanced scheduling features
- Additional AI model integrations

---

## 🔗 API Documentation

### Interactive Documentation

- **Swagger UI**: `https://api.igny8.com/api/docs/`
- **ReDoc**: `https://api.igny8.com/api/redoc/`
- **OpenAPI Schema**: `https://api.igny8.com/api/schema/`

### API Complete Reference

**[API Complete Reference](docs/API-COMPLETE-REFERENCE.md)** - Comprehensive unified API documentation (single source of truth)
- Complete endpoint reference (100+ endpoints across all modules)
- Authentication & authorization guide
- Response format standards (unified format: `{success, data, message, errors, request_id}`)
- Error handling
- Rate limiting (scoped by operation type)
- Pagination
- Roles & permissions
- Tenant/site/sector scoping
- Integration examples (Python, JavaScript, cURL, PHP)
- Testing & debugging
- Change management

### API Standard Features

- ✅ **Unified Response Format** - Consistent JSON structure for all endpoints
- ✅ **Layered Authorization** - Authentication → Tenant → Role → Site/Sector
- ✅ **Centralized Error Handling** - All errors in unified format with request_id
- ✅ **Scoped Rate Limiting** - Different limits per operation type (10-100/min)
- ✅ **Tenant Isolation** - Account/site/sector scoping
- ✅ **Request Tracking** - Unique request ID for debugging
- ✅ **100% Implemented** - All endpoints use unified format

### Quick API Example

```bash
# Login
curl -X POST https://api.igny8.com/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# Get keywords (with token)
curl -X GET https://api.igny8.com/api/v1/planner/keywords/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

### Additional API Guides

- **[Authentication Guide](docs/AUTHENTICATION-GUIDE.md)** - Detailed JWT authentication guide
- **[Error Codes Reference](docs/ERROR-CODES.md)** - Complete error code reference
- **[Rate Limiting Guide](docs/RATE-LIMITING.md)** - Rate limiting and throttling details
- **[Migration Guide](docs/MIGRATION-GUIDE.md)** - Migrating to API v1.0
- **[WordPress Plugin Integration](docs/WORDPRESS-PLUGIN-INTEGRATION.md)** - WordPress integration guide

For backend implementation details, see [docs/04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md).

---

## 📖 Documentation

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

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:**
- **API Documentation**: [API-COMPLETE-REFERENCE.md](docs/API-COMPLETE-REFERENCE.md) - Complete unified API reference (single source of truth)
- **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

### Technology Stack

**Backend:**
- Django 5.2+
- Django REST Framework
- PostgreSQL 15
- Celery 5.3+
- Redis 7

**Frontend:**
- React 19
- 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.