ds

part2-dev/planning/01-strategy.md

@@ -0,0 +1,89 @@
+# 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`
+
+