End-to-End User Flow
How visitors, organization users, enterprise administrators, and platform staff move through the public website, Customer Application, Admin Console, FastAPI backend, PostgreSQL, workers, and external services.
Related: API & Functional Specification · Platform Architecture Flow
Source specifications: End-to-End User Flow (.docx) · API & Functional Specification (.docx) · Platform Architecture Flow (.docx)
Purpose and scope
This guide describes user journeys, business rules, system responsibilities, and expected outcomes across acquisition, trial signup, team collaboration, self-service billing, enterprise provisioning, admin operations, invoicing, background billing jobs, and password reset.
Applications and actors
| Component | Technology / port | Responsibility |
|---|---|---|
| Public website | Next.js :3000 | Product information, pricing, free-trial entry |
| Customer Application | Next.js :3003 | Tenant workspace, team, roles, billing |
| Admin Console | Next.js :3004 | Organizations, plans, subscriptions, invoices, governance |
| Backend | FastAPI /api/v1 | Authentication, authorization, business logic, billing |
| Data and jobs | PostgreSQL + scheduler/worker | Persistence, scheduled processing, notifications |
| External services | Razorpay, Stripe, Email | Payments, webhooks, email delivery |
| Actor | Description |
|---|---|
| Visitor | Unauthenticated website visitor |
| Owner | Creates and manages an organization |
| Enterprise Admin | Administers an enterprise customer workspace |
| Manager / Developer / User | Organization members with scoped permissions |
| Platform Staff / Super Admin | Internal users with platform-level permissions |
Phase 1 — Acquisition
Visitor explores product and pricing, selects Start Free Trial, and is redirected to /auth/signup?trial=15&source=website. Query parameters are context only; the backend must validate trial eligibility.
Outcome: visitor reaches the Customer App signup form.
Phase 2 — Tenant creation
User submits name, email, password, and organization name via POST /auth/signup. The backend validates input and uniqueness, creates organization and owner, assigns the owner role, creates a trialing subscription (15 days, 10 seats), issues tokens, and routes to /command-center. Records are created transactionally.
Outcome: authenticated owner with a newly provisioned trial organization.
Phase 3 — Team and roles
Owner invites a member and selects a role. Backend checks authorization and seat capacity, creates an invitation, and sends email. Invitee opens /accept-invite?token=...; backend validates token, expiry, status, organization, and seat capacity before creating membership. If full, return 402 SEAT_LIMIT_EXCEEDED with no partial membership.
Outcome: member joins the tenant with the selected role.
Phase 4 — Self-service billing
Owner opens Billing, selects Team monthly or annual, and starts Razorpay Checkout. Backend verifies payment through /organization/billing/razorpay/verify and reconciles webhooks. Activate subscription only after server-side verification. Support cancel at period end, resume, renew, seat changes, and a renewal banner when renewal is within five days.
Outcome: active subscription with plan entitlements.
Phase 5 — Subscription access states
Lifecycle states include trialing, active, past_due, suspended, expired, and canceled. Backend computes entitlement mode: full, read_only, or billing_only. Backend enforcement is authoritative; frontend restrictions are supplementary.
Phase 6 — Enterprise provisioning
Account team confirms the contract. Platform staff creates an organization, assigns Enterprise plan, records contract metadata, and invites enterprise_admin. No self-service trial or checkout is assumed.
Phase 7 — Enterprise Customer App
Enterprise admin signs into the Customer App. Billing is read-only (“Managed by your account team”). Organization roles do not grant Admin Console access.
Phase 8 — Platform login gate
Staff opens /login and submits POST /api/auth/login. Backend requires at least one platform.* permission. Organization-only accounts receive 403. Sets ov_admin_access and ov_admin_refresh as secured HttpOnly cookies, loads /auth/me, redirects to /overview.
Phase 9 — Console operations
AdminShell shows permission-filtered navigation: Platform, Access, Billing, Governance. Staff manage organizations, subscriptions, trials, teams, invoices, roles, and plans. Every write creates an audit entry.
Phase 10 — Invoice, payment, reactivation
Staff creates and issues invoices; customer pays via hosted link or staff records offline payment. After verified payment, mark_invoice_paid reconciles records and reactivates eligible subscriptions and entitlements.
Phase 11 — Nightly billing sweep
Scheduler runs trial reminders (D-7/D-13/D-15), past-due suspension, invoice due/overdue reminders. Deduplication keys prevent duplicate messages; deliveries and webhooks are logged.
Phase 12 — Password reset
Customer App uses /auth/forgot-password; Admin Console uses /forgot-password. Backend issues a 30-minute single-use token, validates on reset, and revokes all sessions. Responses must not disclose account existence.
Core business rules
- Organization roles apply only in the Customer Application; platform permissions govern the Admin Console.
- Backend authorization and tenant isolation on every protected API.
- Payment redirects do not prove payment—verify signatures and provider events server-side.
- Payment, webhook, invoice, subscription, and entitlement processing must be idempotent.
- Seat checks before membership creation; no partial records on failure.
- Administrative writes and sensitive billing changes must be auditable.
- Subscription status and entitlement mode are calculated by backend policy.
QA acceptance checklist
Signup
- CTA and signup redirect work
- Duplicate email rejected
- Organization, owner, role, and trial created atomically
- 15-day / 10-seat trial initialized
- Owner reaches command center
Team
- Invitation email and token work
- Expired token rejected
- Seat limit returns 402
- Role-filtered navigation works
- Org roles blocked from console
Billing
- Monthly/annual checkout works
- Payment signature and webhook verified
- Duplicate events are idempotent
- Cancel/resume/seat change rules enforced
- Renewal banner shown within five days
Admin and enterprise
- Platform permission gate works
- Org-only login returns 403
- Admin writes create audit records
- Enterprise contract and invite flow works
- Enterprise billing is read-only
Invoice and jobs
- Draft and issue invoice
- Hosted link/PDF delivered
- Online and offline payment reconciled
- Eligible subscription reactivated
- Reminder deduplication and delivery logs work
Password reset
- 30-minute token expiry
- Single-use token
- Password update
- All sessions revoked
Items to confirm against implementation
- Whether `/auth/signup` is served on port 3003 or a shared domain.
- Whether D-7/D-13/D-15 mean days remaining or elapsed days.
- Trial extension behavior and reminder recalculation.
- Exact rules for trial-seat expansion after invoice payment.
- Cancellation timing and past-due grace period.
- Whether Stripe is enabled for enterprise or self-service.
- Which invoice payments qualify for subscription reactivation.
- Access/refresh token expiry, rotation, CSRF, and revocation.
- Whether customer and platform password-reset flows share token infrastructure.