igny8/master-docs/40-product/ACCOUNT-LIFECYCLE.md

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.