OpenVals
4. Use the platform

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

ComponentTechnology / portResponsibility
Public websiteNext.js :3000Product information, pricing, free-trial entry
Customer ApplicationNext.js :3003Tenant workspace, team, roles, billing
Admin ConsoleNext.js :3004Organizations, plans, subscriptions, invoices, governance
BackendFastAPI /api/v1Authentication, authorization, business logic, billing
Data and jobsPostgreSQL + scheduler/workerPersistence, scheduled processing, notifications
External servicesRazorpay, Stripe, EmailPayments, webhooks, email delivery
ActorDescription
VisitorUnauthenticated website visitor
OwnerCreates and manages an organization
Enterprise AdminAdministers an enterprise customer workspace
Manager / Developer / UserOrganization members with scoped permissions
Platform Staff / Super AdminInternal 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.