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
| Layer | Component | Primary responsibilities |
|---|---|---|
| Presentation | Website — Next.js :3000 | Public pages, pricing, acquisition, signup CTA |
| Presentation | Customer App — Next.js :3003 | Tenant workspace, team, roles, billing |
| Presentation | Admin Console — Next.js :3004 | Platform ops, subscriptions, invoices, governance |
| API / business | FastAPI /api/v1 | Auth, tenant boundaries, billing and admin APIs |
| Persistence | PostgreSQL | Orgs, users, roles, plans, subscriptions, invoices, audit |
| Async processing | Scheduler + worker | Reminders, billing sweep, webhooks, email |
| External | Razorpay / Stripe / Email | Checkout, 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 area | Responsibilities |
|---|---|
| Authentication | Signup, login, me, refresh, logout, password reset, invitation tokens |
| Tenant and membership | Org lifecycle, invitations, seat checks, tenant isolation |
| RBAC | Roles, permissions, platform gate, org permission checks |
| Plans and subscriptions | Catalog, lifecycle, contracts, entitlement calculation |
| Billing and payments | Checkout, verification, webhooks, cancel/resume, seats |
| Invoices | Draft/issue, public access, reconciliation, PDF/link delivery |
| Administration | Overview, org/user/plan management, subscription ops |
| Audit and delivery | Audit trail, webhook history, email delivery records |
| Background processing | Billing 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.