# Pricing and Plans

## Purpose
Describe how plans and pricing are represented in the backend and how plan data is used for credits and limits.

## Code Locations (exact paths)
- Plan and account fields: `backend/igny8_core/auth/models.py` (`Plan`, `Account`)
- Billing limits endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditUsageViewSet.limits`)
- Credit balance endpoint: `backend/igny8_core/modules/billing/views.py` (`CreditBalanceViewSet`)

## High-Level Responsibilities
- Define subscription plans with included credits, billing cycle, pricing, feature flags, account limits, and Stripe metadata.
- Attach plans to accounts and expose plan-based limits and credits to billing endpoints.
- Keep credit computations aligned with `included_credits` via `Plan.get_effective_credits_per_month`.

## Detailed Behavior
- `Plan` fields:
  - Pricing: `price`, `billing_cycle` (`monthly/annual`), `extra_credit_price`, `allow_credit_topup`, optional auto-topup thresholds/amounts.
  - Credits: `included_credits` (preferred) with legacy `credits_per_month` fallback via `get_effective_credits_per_month`.
  - Limits: `max_users`, `max_sites`, `max_industries`, `max_author_profiles`.
  - Stripe: `stripe_product_id`, `stripe_price_id`.
  - Features: JSON `features` list; `is_active` flag.
  - Validation ensures `max_sites >= 1`, `included_credits >= 0`.
- `Account` fields:
  - `plan` FK, `credits` balance, status (active/suspended/trial/cancelled), billing contact/address fields, tax_id, retention days, Stripe customer id.
  - Soft-delete guard prevents deleting system accounts.
- Limits computation (billing `limits` endpoint):
  - Calculates current usage counts (users, sites, industries, author profiles) and returns alongside plan limits.
  - Returns empty limits when account or plan is missing to keep UI resilient.
- Credit balance:
  - Balance endpoint includes `plan_credits_per_month` using `Plan.get_effective_credits_per_month`.

## Data Structures / Models Involved (no code)
- `Plan`, `Account` (plan attachment, credits, limits, billing info).

## Execution Flow
- Account creation/association sets `plan`; credit balance endpoints read plan credits and account credits.
- Limits endpoint reads plan limits and computes current usage counts per account.
- Credit usage/deductions run against `Account.credits`; top-ups/invoices handled through billing services.

## Cross-Module Interactions
- Billing endpoints surface plan credits and limits; credit cost/deductions happen in billing services.
- Automation start checks `Account.credits` but not plan limits; plan status enforced in `AccountContextMiddleware` (requires active plan).

## State Transitions
- Plan activation toggles `is_active`; account plan changes immediately affect limits/balance reporting.
- Account status/plan changes enforced at middleware for access gating.

## Error Handling
- Plan validation errors for invalid limits/credits on save; billing endpoints return empty limits when plan/account missing instead of failing.

## Tenancy Rules
- Plans are global; accounts reference a single plan. All limit calculations are per account.

## Billing Rules
- Credits included per plan reported via balance endpoint; extra credit price/top-up fields are present but actual purchase flows are through credit packages/invoices (not auto-charging in code shown).

## Background Tasks / Schedulers
- None specific to plans; any subscription renewal logic would generate invoices/payments via billing services (not implemented here).

## Key Design Considerations
- `included_credits` supersedes legacy `credits_per_month`; keep `get_effective_credits_per_month` for backward compatibility.
- Limits are informational in the billing module; enforcement must occur in the respective domains if required.

## How Developers Should Work With This Module
- When adding new plan features or limits, extend `Plan` fields and ensure billing limits endpoint surfaces them.
- Use `get_effective_credits_per_month` wherever plan credits are displayed or calculated.
- Keep plan validation consistent (non-negative credits, minimum site/user counts).