# User Flow Overview
 
 ## Purpose
 Describe the end-to-end journey from signup through planning, writing, automation, publishing, and billing within IGNY8, mapping each step to concrete backend/frontend modules so engineers can navigate without scanning code.
 
 ## Code Locations (exact paths)
 - Auth & account: `backend/igny8_core/auth/{views.py,serializers.py,models.py,middleware.py}`, `frontend/src/store/authStore.ts`, routes in `frontend/src/App.tsx`
 - Planner: `backend/igny8_core/modules/planner/views.py`, `business/planning/models.py`, `frontend/src/pages/Planner/*`
 - Writer: `backend/igny8_core/modules/writer/views.py`, `business/content/models.py`, `frontend/src/pages/Writer/*`
 - Automation: `backend/igny8_core/business/automation/{services/automation_service.py,tasks.py,views.py}`, `frontend/src/pages/Automation/AutomationPage.tsx`
 - Publishing/Integration: `backend/igny8_core/business/integration/{models.py,services/integration_service.py}`, `modules/integration/views.py`, WordPress plugin endpoints consumed via `/api/v1/integration/`; `frontend/src/pages/Sites/*`
 - Billing: `backend/igny8_core/business/billing/{models.py,services/credit_service.py,services/invoice_service.py,views.py}`, `frontend/src/pages/account/*`
 - Tenancy enforcement: `backend/igny8_core/auth/middleware.py`, `backend/igny8_core/api/base.py`
 
 ## High-Level Responsibilities
 - Authenticate users and attach account context to every request.
 - Let users plan keywords/clusters/ideas, create tasks and content, optionally automate all seven pipeline stages.
 - Manage sites/sectors and connect WordPress for publishing/sync.
 - Track credits, plans, subscriptions, invoices, and payments through billing services.
 
 ## Detailed Behavior
 - Signup/Login: `auth/views.py` issues JWTs; `AccountContextMiddleware` sets `request.account`; frontend `authStore` stores tokens and refreshes them.
 - Planning: `KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet` create/list/update scoped by `SiteSectorModelViewSet` filters; frontend planner pages drive these endpoints.
 - Writing: `TasksViewSet`, `ContentViewSet`, `ImagesViewSet` manage tasks/content/images; AI generation endpoints trigger Celery-backed functions.
 - Automation: `AutomationViewSet` + `automation_service.py` orchestrate 7 stages (keywords→clusters→ideas→tasks→content→image-prompts→images/manual review) with pause/resume and credit estimation; Celery tasks `run_automation_task`/`resume_automation_task` execute runs.
 - Publishing/Integration: `IntegrationViewSet` handles WP connection tests and sync; WP plugin sends/receives data via API key; content publish endpoints in writer module update WordPress via integration services.
 - Billing: credit balances and costs computed in `credit_service.py`; invoices via `invoice_service.py`; payments via `payment_service.py`; endpoints in `modules/billing/views.py` feed frontend billing pages.
 
 ## Data Structures / Models Involved (no code)
 - Tenancy: `Account`, `Site`, `Sector` (plus `SiteUserAccess`), base models `AccountBaseModel`/`SiteSectorBaseModel`.
 - Planning: `Keywords`, `Clusters`, `ContentIdeas`.
 - Writing: `Tasks`, `Content`, `Images`.
 - Automation: `AutomationConfig`, `AutomationRun`.
 - Billing: `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `Subscription`, `Plan`.
 - Integration: `SiteIntegration`.
 
 ## Execution Flow
 1) User signs in → JWT stored → `AccountContextMiddleware` populates `request.account`.
 2) Tenant creates sites/sectors (`SiteViewSet`), selects industry/sectors, optionally connects WordPress.
 3) Planner: upload/enter keywords → cluster → generate ideas (manual or via automation/AI functions).
 4) Writer: create tasks from ideas, generate content/images (manual endpoints or automation stages).
 5) Publish: send to WordPress via integration endpoints or automation publish step; WP plugin syncs back statuses.
 6) Automation (optional): run 7-stage pipeline via `AutomationViewSet` + Celery tasks; pause/resume supported.
 7) Billing: credits deducted per AI/pipeline usage (`credit_service`), invoices/payments recorded; users view in billing pages.
 
 ## Cross-Module Interactions
 - Automation invokes planner/writer endpoints/services and logs credit estimates.
 - Billing hooks into automation and writer AI calls via credit deduction utilities.
 - Integration uses site/account context and WP API key for sync; writer publish flows depend on integration configuration.
 
 ## State Transitions (if applicable)
 - Account status (`active/suspended/trial/cancelled`) governs access; plan/subscription affect limits.
 - Tasks/content/images status transitions handled in writer endpoints; automation run status moves through `created/running/paused/completed/failed`.
 - Site activation via `set_active`; sectors toggled via `select_sectors`.
 
 ## Error Handling
 - Unified API responses via `api/response.py`; DRF exception handler configured in settings; frontend shows toasts/banners.
 - Automation errors logged via `automation_logger`; tasks wrapped in Celery with retries where defined.
 
 ## Tenancy Rules
 - `AccountContextMiddleware` sets `request.account`; base viewsets filter by account/site/sector; API key auth sets account from `Site.wp_api_key`; public site slug reads limited to active sites.
 
 ## Billing Rules (if applicable)
 - AI/automation uses `CreditService.deduct_credits_for_action`; credit balance required before runs; plans/subscriptions define included credits and sector/site limits.
 
 ## Background Tasks / Schedulers (if applicable)
 - Celery tasks: automation runs (`run_automation_task`, `resume_automation_task`), scheduler `check_scheduled_automations`, AI functions (`ai/tasks.py`), publishing tasks (`tasks/wordpress_publishing.py`).
 
 ## Key Design Considerations
 - Strong tenant isolation via middleware + filtered querysets.
 - Automation relies on polling and Celery; frontend automation page polls every 5s during runs.
 - Billing is authoritative in backend; frontend is read-only except initiating purchases/subscriptions.
 
 ## How Developers Should Work With This Module
 - Trace user-visible flows by following router → page component → service call → backend viewset.
 - When adding steps, ensure credit deductions and tenancy filters are applied in the corresponding backend service/viewset.
 - Keep WP integration changes consistent with API key auth and `SiteIntegration` schema.