# Account Lifecycle
 
 ## Purpose
 Explain how accounts are created, activated, associated with plans/subscriptions, how users access them, and how account state affects the platform.
 
 ## Code Locations (exact paths)
 - Models: `backend/igny8_core/auth/models.py` (`Account`, `User`, `Plan`, `Subscription`, `Site`, `SiteUserAccess`)
 - Auth middleware: `backend/igny8_core/auth/middleware.py` (sets `request.account`, validates plan status)
 - Permissions: `backend/igny8_core/auth/permissions.py`
 - Account settings API: `backend/igny8_core/modules/system/views.py` (account settings), `auth/views.py` (team)
 - Frontend account settings: `frontend/src/pages/account/AccountSettingsPage.tsx`
 - Frontend auth store: `frontend/src/store/authStore.ts`
 
 ## High-Level Responsibilities
 - Maintain tenant identity (`Account`) and link users, sites, sectors, plans, subscriptions, and credits.
 - Control access via account state and user roles.
 - Provide account-level settings (name, billing email/address, tax info).
 
 ## Detailed Behavior
 - Account fields: `name`, `slug`, `owner`, `plan`, `credits`, `status` (`active`, `suspended`, `trial`, `cancelled`), timestamps.
 - User fields: extends Django user with `account` FK and `role` (`developer`, `owner`, `admin`, `editor`, `viewer`, `system_bot`).
 - Plan/subscription: `Plan` defines limits and included credits; `Subscription` links account to plan and holds billing cycle/status; `Account.plan` references current plan.
 - Sites: `Site` attaches to account; `SiteUserAccess` grants non-admin users site-level access.
 - Middleware: `AccountContextMiddleware` resolves account from JWT or session, ensures account is active, and attaches plan information; rejects access for inactive accounts.
 - Settings update: `AccountSettings` API exposes billing fields consumed by `AccountSettingsPage`.
 
 ## Data Structures / Models Involved (no code)
 - `Account`, `User`, `Plan`, `Subscription`, `Site`, `SiteUserAccess`, `Sector`, `CreditTransaction`, `CreditUsageLog`.
 
 ## Execution Flow
 - Signup/Login → JWT issued with `account_id` → middleware sets `request.account`.
 - Requests pass through permissions tied to roles and account context.
 - Plan changes/subscriptions update `Account.plan` and `Subscription` records (via billing endpoints and `invoice_service`/`payment_service`).
 - Account settings updates persist via system/account settings endpoint and reflect in billing data.
 
 ## Cross-Module Interactions
 - Billing uses `Account.credits` and plan linkage; `credit_service` deducts/credits per action.
 - Sites/Planner/Writer/Automation all inherit account scoping via base viewsets and base models.
 - Integration (WordPress) uses account-scoped `Site.wp_api_key` for API key auth.
 
 ## State Transitions (if applicable)
 - `status`: trial → active → (suspended/cancelled) based on plan/payment handling (enforced via middleware checks).
 - `plan` changes when subscriptions are created/updated; `Subscription.status` drives billing state.
 - Site activation independent per site; account state still gates overall access.
 
 ## Error Handling
 - Middleware rejects requests for inactive/suspended accounts; API returns unified error response.
 - Permissions reject unauthorized roles before hitting business logic.
 
 ## Tenancy Rules
 - Every model inherits account (direct FK or via base models); every request resolves `request.account`.
 - Querysets in viewsets filter by `account` (and site/sector where applicable); public reads limited to specific cases (e.g., active site by slug).
 
 ## Billing Rules (if applicable)
 - Plan inclusion and subscription determine credit grants; credits stored on `Account`; deductions logged via `CreditTransaction`/`CreditUsageLog`.
 
 ## Background Tasks / Schedulers (if applicable)
 - None specific to account state; billing/automation tasks run with account context provided by Celery payloads.
 
 ## Key Design Considerations
 - Account is the tenant boundary; all downstream objects carry account FK for isolation.
 - Middleware centralizes account activation/plan validation to avoid per-view duplication.
 
 ## How Developers Should Work With This Module
 - When adding new resources, inherit from `AccountBaseModel`/`SiteSectorBaseModel` and use base viewsets to enforce scoping.
 - On new plan features/limits, extend `Plan` and ensure middleware/permissions or service checks enforce them.
 - Preserve slug immutability for stability across integrations.