# IGNY8 Phase 2 Strategy & Architecture

## Purpose
Single reference for the “why” and “what” behind Phase 2, combining the original `ARCHITECTURE_CONTEXT.md` and the strategic sections of `IGNY8-HOLISTIC-ARCHITECTURE-PLAN.md`. Use this doc to align stakeholders before diving into workflows, phases, or roadmap specifics.

---

## Executive Summary
- IGNY8 is a multi-tenant SaaS for SEO planning and AI content creation. Accounts own sites, sites contain sectors, and all planner/writer activity is scoped to that hierarchy.
- The refreshed strategy focuses on a **cluster-first planning engine**, **state-aware site builder**, and **shared metadata across Planner, Writer, Linker, Optimizer, and WordPress sync**.
- Platform foundations: Django 5.2 + DRF backend, React 19 frontend, PostgreSQL, Redis, Celery, Dockerized infra with Caddy reverse proxy.

### Guiding Principles
1. **Multi-tenancy everywhere** – automatic account/site/sector scoping in models & viewsets.
2. **Configuration-driven UX** – shared templates, centralized API client, environment-configurable AI prompts.
3. **Unified AI engine** – all AI calls flow through `AIEngine` via Celery, with credit tracking and progress reporting.
4. **Stage-gated workflows** – users move through guided wizards (Planner → Site Builder → Writer → Publish) with clear prerequisites.

---

## Architecture Overview
### Layers
| Layer | Responsibilities |
| --- | --- |
| **Client Apps** | Main SaaS app (`app.igny8`), marketing site, admin tooling. |
| **Reverse Proxy** | Caddy terminates TLS and routes traffic. |
| **Application Services** | React frontend (8021), Django backend (8011), Celery worker/beat. |
| **Data & Storage** | PostgreSQL, Redis, `/data/app/sites-data` for site deployments. |
| **External Integrations** | OpenAI/Runware for AI, WordPress for publishing, future Shopify. |

### Module Snapshot
- **Planner**: Keywords, Clusters, Ideas, clustering AI.
- **Writer**: Tasks, Content, Images, AI generation, WordPress publishing.
- **Site Builder**: Blueprints, page scaffolding, deployment adapters.
- **System/Integration**: Settings, API keys, sync adapters.
- **Billing**: Credits, transactions, usage logs.

---

## Data Hierarchy & Access
```
Account → Site → Sector → (Keywords, Clusters, Ideas, Tasks, Content, Images)
```
- Roles (`developer > owner > admin > editor > viewer > system_bot`) determine automatic access.
- Editors/Viewers require explicit `SiteUserAccess`.
- Middleware injects `request.account`; viewsets enforce scoping.

---

## Key Workflows (High-Level)
1. **Account Setup** – create account/site/sector, configure integrations, assign roles.
2. **Planner** – import keywords, auto-cluster, attach clusters to site builder.
3. **Writer** – turn ideas into tasks, run AI content generation, manage reviews.
4. **Publishing** – deploy to IGNY8 renderer or sync to WordPress (future Shopify).

Detailed mechanics live in `02-workflows.md`.

---

## AI Framework Snapshot
- Entry point: `run_ai_task(function_name, payload, account_id)`.
- Six-phase pipeline (INIT → PREP → AI_CALL → PARSE → SAVE → DONE).
- Functions currently: `auto_cluster`, `generate_ideas`, `generate_content`, `generate_image_prompts`, `generate_images`.
- Credits deducted post-success; each function declares cost.

---

## Security & Ops
- JWT auth with 15 min access / 7 day refresh, stored client-side.
- Role-based authorization on every request.
- Dockerized infra split between `igny8-infra` (Postgres, Redis, Caddy, etc.) and `igny8-app` (backend/frontend/worker).
- External services configured per account via Integration Settings.

---

## Current Strategic Priorities
1. **Cluster-first planning** – enforce keyword clusters before site planning.
2. **Taxonomy-aware site builder** – blog/ecommerce/company flows with state-aware wizard.
3. **Unified content metadata** – propagate cluster/taxonomy data through writer, linker, optimizer, and publishing.
4. **WordPress parity** – treat synced WP sites as first-class citizens without duplicating site data.

---

## References
- Detailed workflows: `02-workflows.md`
- Phase reports & learnings: `03-phase-reports.md`
- Execution roadmap: `04-roadmap.md`