## IGNY8 User & Billing Flow — Current State and Remediation Plan ### 0) Scope / Sources - Frontend routing: `frontend/src/App.tsx` - Auth store and token handling: `frontend/src/store/authStore.ts` - Balance/usage/billing client: `frontend/src/services/api.ts`, `frontend/src/services/billing.api.ts` - Admin billing UI: `frontend/src/pages/Admin/AdminBilling.tsx` - Backend auth/billing routers: `backend/igny8_core/auth/urls.py`, `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py` --- ### 1) Signup / Login **Backend endpoints (auth/urls.py)** - POST `/api/v1/auth/register/` → creates user; no email verification enforced. - POST `/api/v1/auth/login/` → issues JWT access/refresh; requires valid account + plan for “happy path”. - POST `/api/v1/auth/refresh/` → refresh token. **Frontend behavior (authStore)** - `register()` hits `/v1/auth/register/`; on success stores tokens and marks authenticated. - `login()` hits `/v1/auth/login/`; if user.account missing → throws `ACCOUNT_REQUIRED`; if plan missing → `PLAN_REQUIRED`. So the UI blocks login success if the account/plan is absent. - After login, routes are guarded by `ProtectedRoute` → land on main dashboard (`/`). **Gaps** - No email verification or onboarding; user is dropped to dashboard. - If account/plan is missing, errors surface but no guided remediation (no redirect to plan selection). --- ### 2) Tenant Billing Data & Balance **Current endpoints used** - Balance: `/v1/billing/transactions/balance/` (business billing CreditTransactionViewSet.balance). - Credit transactions: `/api/v1/billing/transactions/`. - Usage logs/summary/limits: `/api/v1/billing/credits/usage/…`, `/v1/billing/credits/usage/summary/`, `/v1/billing/credits/usage/limits/`. - Invoices: `/api/v1/billing/invoices/` (+ detail, pdf). - Payments: `/api/v1/billing/payments/`. - Credit packages: `/v1/billing/credit-packages/`. **UI touchpoints** - Header metric uses `fetchCreditBalance()` → `/v1/billing/transactions/balance/`. - Usage & Analytics, Credits pages, Billing panels use `getCreditBalance()` → same endpoint. **Gaps** - Subscription lifecycle (select plan, subscribe/upgrade/cancel) not wired in UI. - Payment methods add/remove not exposed in UI. - Balance fetch falls back to zero on any non-200; no inline “balance unavailable” messaging. --- ### 3) Admin Billing (pages/Admin/AdminBilling.tsx) **Current tabs & data** - Overview: stats from `/v1/admin/billing/stats/` (totals, usage). - User Management: `/v1/admin/users/` (credit balances), adjust credits via `/v1/admin/users/{id}/adjust-credits/`. - Credit Pricing: `/v1/admin/credit-costs/` with editable cost per operation; Save posts updates. - Credit Packages: read-only cards from `/v1/billing/credit-packages/`. **Gaps** - No admin CRUD for packages (only read). - No exports/filters for payments/invoices in this page (handled elsewhere). --- ### 4) Plan Limits / Access **Backend** - Auth login blocks if account plan missing (frontend enforced). Backend exposes plans/subscriptions via `auth/urls.py` (routers: `plans`, `subscriptions`). - Automation service checks `account.credits` directly before heavy AI work (no HTTP). **Frontend** - No explicit plan-limit enforcement in UI (sites, seats, module gating) beyond route/module guards already present per module. - No upgrade prompts when hitting limits. --- ### 5) AI / Automation Credit Checks - Backend: `automation_service.py` estimates credits, adds 20% buffer, aborts if `account.credits` < required. Not dependent on billing APIs. - Frontend: no preflight credit warning; errors are backend-driven. --- ### 6) What’s Missing for a Complete E2E Paid Flow 1) **Subscription UX**: Add tenant plan selection + subscribe/upgrade/cancel wired to `/api/v1/auth/subscriptions/...` (or billing subscription endpoints if exposed separately). Show current plan and renewal status. 2) **Payment Methods**: Expose add/list/remove default; required for Stripe/PayPal/manual flows. 3) **Invoices/Payments (tenant)**: List history with PDF download; surface payment status. 4) **Manual payments (if supported)**: Provide upload/reference input; show approval status. 5) **Plan limits**: Enforce and message limits on sites, seats, modules; show “Upgrade to increase limit.” 6) **Balance UX**: If `/v1/billing/transactions/balance/` fails, show inline warning and retry instead of silently showing 0. 7) **Admin packages**: If needed, add CRUD for credit packages (activate/feature/sort/price IDs). 8) **Onboarding**: Post-signup redirect to “Choose plan” if no active plan; optional email verification. --- ### 7) Recommended Happy Path (Target) 1) Signup → email verify (optional) → redirect to Plan selection. 2) Choose plan → subscribe (create payment method + subscription intent) → confirm → landing on dashboard with non-zero credits and plan limits loaded. 3) User can: - Add sites up to plan limit. - Use Planner/Writer modules; preflight check shows remaining credits. - View Credits/Usage/Invoices/Payments; purchase extra credit packages if needed. 4) Header shows live balance from `/v1/billing/transactions/balance/`; errors visible if fetch fails. 5) Admin can: - Adjust credit costs, see stats/payments/invoices/approvals. - Manage credit packages (CRUD) if enabled. --- ### 8) Quick Endpoint Reference (current wiring) - Balance: `/v1/billing/transactions/balance/` - Tenant: invoices `/api/v1/billing/invoices/`, payments `/api/v1/billing/payments/`, credit-packages `/v1/billing/credit-packages/`, usage `/api/v1/billing/credits/usage/` - Admin: stats `/v1/admin/billing/stats/`, users `/v1/admin/users/`, credit-costs `/v1/admin/credit-costs/`, admin payments `/v1/billing/admin/payments/`, pending approvals `/v1/billing/admin/pending_payments/` --- ## Remediation Plan (Do Now) ### A) Access control / onboarding - After register → force redirect to Plans page. - Lock all app routes except Account Profile, Plans, Billing until subscription is active (route guard). - Optional: email verification gate before plan selection. ### B) Plans & subscription UX (tenant) - Plans page: list plans from `/api/v1/auth/plans/` (or billing subscriptions endpoint), show limits. - Actions: subscribe/upgrade/cancel wired to subscription endpoints; show status/renewal date. - CTA in header/sidebar if no active plan. ### C) Payment methods - Add/list/remove default payment methods (Stripe/PayPal/manual) via billing endpoints. - Show “add payment method” inline on Plans/Billing if none exists. ### D) Checkout / payments - Credit packages purchase flow wired to `/v1/billing/credit-packages/…/purchase/`. - If manual payments allowed: upload/reference form and surface status; tie to admin approvals. - Invoice list/history with PDF download; payment history with status badges. ### E) Balance and usage UX - Use single endpoint `/v1/billing/transactions/balance/`; on non-200 show inline warning + retry (no silent zero). - Surface plan limits and usage (sites, seats, module access) with upgrade prompts when near/at limit. ### F) Module access & limits - Enforce plan limits on: add site, team invites, module guards (planner/writer/automation/etc.). - On 403/422 from backend: show upgrade prompt with link to Plans. ### G) Admin - Optional: add CRUD for credit packages (create/edit/sort/feature) if backend endpoints available. - Keep credit costs editable (already wired); add filters/exports later if needed. ### H) AI task preflight - Before costly AI actions, fetch balance and show “insufficient credits—purchase/upgrade” prompt. - Handle backend credit errors with actionable UI (purchase/upgrade CTA). ### I) Error handling / UX polish - Balance widget: display “Balance unavailable” on error; retry button. - Centralize billing error toasts with clear messages (404 vs 402/403 vs 500). ### J) Implementation order 1) Route guard + post-signup redirect to Plans; hide other routes until active plan. 2) Plans page with subscribe/upgrade/cancel wiring; add payment method UI. 3) Billing page: invoices/payments/history + credit package purchase CTA. 4) Balance/usage error handling; plan limit prompts; AI preflight checks. 5) Admin package CRUD (if needed) and exports/filters. [User lands] | v [/signup] -- create account --> [Tokens stored] | v [/account/plans] (onboarding gate) | |-- list plans (/v1/auth/plans/) |-- choose plan + payment method (default/selected) |-- subscribe (/v1/auth/subscriptions/) v [Plan active] -----> [Billing tabs available] | | \ | | \ | v v | [Purchase Credits] [Invoices/Payments] | /api/v1/... (list + PDF download) | | | v | [Balance/Usage/Limits] (shared store, retry) | v [Protected routes unlocked: /, modules, account] | v [Sites -> Add/Manage site] | |-- check plan limits (sites/seats/modules) |-- on limit: show upgrade/purchase prompt v [Site created] | v [Start workflow] |-- Planner/Writer/Automation, etc. |-- preflight: balance/limits; on 402/403 -> prompt upgrade/purchase v [User executes tasks with credits]