# Billing Lifecycle
 
 ## Purpose
 Detail how credits, plans, subscriptions, invoices, and payments flow through the system, and where deductions/additions are enforced.
 
 ## Code Locations (exact paths)
 - Models: `backend/igny8_core/business/billing/models.py` (`CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `PaymentMethodConfig`, `AccountPaymentMethod`)
 - Services: `backend/igny8_core/business/billing/services/credit_service.py`, `services/invoice_service.py`, `services/payment_service.py`
 - Views/Endpoints: `backend/igny8_core/modules/billing/views.py`
 - Frontend billing pages: `frontend/src/pages/account/{AccountBillingPage.tsx,PlansAndBillingPage.tsx,PurchaseCreditsPage.tsx}`
 
 ## High-Level Responsibilities
 - Track credit balance, record usage, and enforce costs for AI/automation actions.
 - Manage plans/subscriptions, generate invoices, and record payments.
 - Expose account-scoped billing data (balance, usage, invoices, payments, packages, payment methods).
 
 ## Detailed Behavior
 - Credit balance: stored on `Account.credits`; `CreditService` adds/deducts via `CreditTransaction` and logs usage in `CreditUsageLog`.
 - Costs: read from `CreditCostConfig` or hardcoded `CREDIT_COSTS` fallbacks inside `credit_service.py`.
 - Deductions: called from AI/automation flows to ensure sufficient credits; `InsufficientCreditsError` thrown on shortage.
 - Plans/Subscriptions: `Plan` defines price, billing_cycle, included_credits, max sites/sectors/users; `Subscription` links account to plan. Plan selection handled via billing endpoints and frontend plan tabs.
 - Invoices: `InvoiceService` creates invoices for subscriptions and credit packages; generates unique invoice numbers and line items.
 - Payments: `PaymentService` records payments; manual payments stored with status (pending/processing/etc.); payment methods configured via `PaymentMethodConfig`/`AccountPaymentMethod`.
 - Packages: `CreditPackage` defines purchasable credit bundles; purchasing triggers invoice/payment flows.
 
 ## Data Structures / Models Involved (no code)
 - Billing: `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `Invoice`, `Payment`, `CreditPackage`, `PaymentMethodConfig`, `AccountPaymentMethod`.
 - Plan: `Plan`, `Subscription` (in `auth/models.py`).
 - Account linkage: `Account` holds `credits` and `plan`.
 
 ## Execution Flow
 - Balance/Usage read: billing endpoints return account-scoped balance and usage summaries.
 - AI/Automation call: service invokes `CreditService.deduct_credits_for_action` → creates `CreditTransaction` + `CreditUsageLog`.
 - Purchase credits: frontend calls billing endpoint → `CreditService.add_credits` + `InvoiceService` for package; payment recorded via `PaymentService` (manual/other).
 - Subscription change: endpoint updates `Subscription` + `Account.plan`, generates invoice as needed; payment recorded if required.
 - Invoice download: `modules/billing/views.py` exposes invoice retrieval; frontend uses `downloadInvoicePDF`.
 
 ## Cross-Module Interactions
 - Automation/writer AI calls depend on credit checks; insufficient balance blocks operations.
 - Account settings feed invoice billing details; payments/invoices are tied to account.
 
 ## State Transitions (if applicable)
 - Payment status: `pending` → `processing/pending_approval` → `succeeded/completed` or `failed/refunded/cancelled/void/uncollectible`.
 - Subscription status: `active`/`cancelled` (persisted in `Subscription`); plan reference on account updates accordingly.
 
 ## Error Handling
 - `InsufficientCreditsError` for low balance; surfaces to API as error response.
 - Payment/Invoice service raise validation errors (e.g., already paid invoice).
 
 ## Tenancy Rules
 - All billing queries filter by `request.user.account`; viewsets inherit from `AccountModelViewSet`.
 - Payment methods, invoices, payments, credit transactions are account-scoped; no cross-tenant access.
 
 ## Billing Rules (if applicable)
 - Costs derived from config constants or `CreditCostConfig`.
 - Included credits and limits come from `Plan`; extra purchases via `CreditPackage`.
 - Credits must be available before AI/automation runs proceed.
 
 ## Background Tasks / Schedulers (if applicable)
 - None dedicated; billing operations are request-driven. Automation tasks carry account context to deduct credits within Celery runs.
 
 ## Key Design Considerations
 - CreditService centralizes deductions to avoid scattered logic.
 - Manual payment flow avoids storing sensitive data; relies on transaction_reference and admin approval.
 
 ## How Developers Should Work With This Module
 - When adding new billable actions, route them through `CreditService` with a defined cost key.
 - To change pricing, update `CreditCostConfig` data or the `CREDIT_COSTS` fallback map.
 - Keep all billing endpoints inheriting `AccountModelViewSet` to maintain isolation.