salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2420f1678d4a897890c56ec95e8cff423d799fd6
igny8/user-flow-plan.md
IGNY8 VPS (Salman) 2420f1678d docs 1
2025-12-07 11:28:32 +00:00

9.2 KiB
Raw Blame History

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]

Reference in New Issue View Git Blame Copy Permalink