# 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
├── 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 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-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) for complete API reference.

---

## 📖 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:**
- **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.
