OpenVals
4. Use the platform

Platform Architecture Flow

Logical architecture and interactions between the public website, Customer Application, Admin Console, FastAPI backend, PostgreSQL, background processing, and external providers. Confirm deployment topology against the live environment.

Related: End-to-End User Flow · API & Functional Specification

Source specifications: End-to-End User Flow (.docx) · API & Functional Specification (.docx) · Platform Architecture Flow (.docx)

High-level architecture

LayerComponentPrimary responsibilities
PresentationWebsite — Next.js :3000Public pages, pricing, acquisition, signup CTA
PresentationCustomer App — Next.js :3003Tenant workspace, team, roles, billing
PresentationAdmin Console — Next.js :3004Platform ops, subscriptions, invoices, governance
API / businessFastAPI /api/v1Auth, tenant boundaries, billing and admin APIs
PersistencePostgreSQLOrgs, users, roles, plans, subscriptions, invoices, audit
Async processingScheduler + workerReminders, billing sweep, webhooks, email
ExternalRazorpay / Stripe / EmailCheckout, callbacks, invitations, notifications

Public acquisition and signup

  • Visitor requests public website pages.
  • Website CTA redirects to Customer App signup with source context.
  • Customer App submits signup to FastAPI.
  • Backend transactionally creates tenant, owner, role, and trial subscription.
  • Backend issues session credentials; Customer App opens command center.

Authenticated customer requests

  • Customer App sends API requests with authenticated session.
  • Backend resolves organization membership and checks role/permission.
  • Entitlement service checks subscription state, plan limits, and seats.
  • Business service reads/writes tenant-scoped PostgreSQL records.
  • Response returns; UI reflects authorized state.

Admin Console requests

  • Staff authenticates through Admin Console login.
  • Backend requires at least one platform.* permission.
  • Admin session uses protected cookies; navigation is permission-filtered.
  • Each administrative API independently verifies platform permission.
  • Writes persist business changes and an audit event.

Payment and webhook flow

  • Customer starts checkout or public invoice payment.
  • Backend creates or retrieves payment order and provider checkout context.
  • Provider processes transaction; browser result and webhook reach verification paths.
  • Backend verifies signature, event identity, amount, currency, and state.
  • Idempotent reconciliation updates payment, invoice, subscription, entitlements.
  • Audit and notification events are recorded.

Background billing flow

  • Scheduler triggers billing sweep.
  • Worker evaluates trial, subscription, and invoice dates.
  • Worker applies transitions and creates notification work.
  • Deduplication key checked before sending email.
  • Delivery result and provider webhook recorded.

Logical backend service boundaries

Service areaResponsibilities
AuthenticationSignup, login, me, refresh, logout, password reset, invitation tokens
Tenant and membershipOrg lifecycle, invitations, seat checks, tenant isolation
RBACRoles, permissions, platform gate, org permission checks
Plans and subscriptionsCatalog, lifecycle, contracts, entitlement calculation
Billing and paymentsCheckout, verification, webhooks, cancel/resume, seats
InvoicesDraft/issue, public access, reconciliation, PDF/link delivery
AdministrationOverview, org/user/plan management, subscription ops
Audit and deliveryAudit trail, webhook history, email delivery records
Background processingBilling sweep, reminders, suspension, deduplication

Data and trust boundaries

  • Browser clients are untrusted—validate inputs and authorization on the backend.
  • Customer tenant data scoped by authenticated organization context.
  • Admin APIs require platform permissions; hidden nav is not authorization.
  • Payment callbacks untrusted until signature and event validation.
  • Public invoice pages expose only minimum data per token/link policy.
  • Secrets, provider credentials, and tokens must not leak to client storage or logs.
  • Background jobs must be safe to retry without duplicate financial or notification effects.

Resilience and observability

  • Correlation IDs across frontend, backend, workers, and provider callbacks.
  • Record webhook event IDs and outcomes for idempotency and replay investigation.
  • Bounded retries with backoff for transient provider/email failures.
  • Track queue depth, job age, failures, email status, reconciliation failures.
  • Critical multi-entity updates use database transactions.
  • Alert on repeated payment verification failures, stuck jobs, failed delivery.

Architecture decisions to validate

  • Whether three Next.js apps share a domain, use separate domains, or sit behind a reverse proxy.
  • Cookie domain, SameSite, CSRF, and CORS for cross-app authentication.
  • Whether webhook handlers run in the API process or a dedicated worker.
  • Scheduler technology, worker concurrency, locking, and retry policy.
  • PostgreSQL transaction boundaries and uniqueness for payment/webhook idempotency.
  • Storage location and retention for invoice PDFs and audit records.